Skip to content
Back to search

ahrefs-mcp-server

Official Ahrefs MCP Server

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ahrefs--ahrefs-mcp-server/badge.svg)](/listings/ahrefs--ahrefs-mcp-server)

HTML

<a href="/listings/ahrefs--ahrefs-mcp-server"><img src="/api/listings/ahrefs--ahrefs-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

`npm` commands need to be executed in a terminal: - macOS: open the Terminal from your Applications folder - Windows: press Windows + R, type `cmd`, and press Enter

Install Node.js and npm

1. Download Node.js from [nodejs.org](https://nodejs.org/en/download/) 2. Follow the installation instructions for your operating system 3. Verify installation by running:

npm -v

4. A version number will be printed if installation was successful

Windows Users

- When installing Node.js, use the official installer and make sure the folder is added to PATH when selecting installation options.

Install Ahrefs MCP Server

npm install --prefix=~/.global-node-modules @ahrefs/mcp -g

Upgrading versions

If you've installed our MCP server before, and just want to upgrade, run this command:

npm install --prefix=~/.global-node-modules @ahrefs/mcp@latest -g

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 316 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. > [!WARNING]
  2. > This repository is no longer maintained!
  3. > We have released a **remote Ahrefs MCP server**, which doesn't require local setup and works directly in popular AI tools.
  4. > Learn more here: [Remote MCP server documentation](https://docs.ahrefs.com/docs/mcp/reference/introduction)
  5. >
  6. > This repository is for the **local Ahrefs MCP server** which works with API v3 keys only. It **DOES NOT** work with MCP keys. It **IS NOT** maintained. It is **OUTDATED**. And we do not recommend using it.
  7. # Ahrefs MCP
  8. A Model Context Protocol server to connect Claude desktop and other compatible AI assistants to Ahrefs.
  9. ## Installation
  10. `npm` commands need to be executed in a terminal:
  11. - macOS: open the Terminal from your Applications folder
  12. - Windows: press Windows + R, type `cmd`, and press Enter
  13. ### Install Node.js and npm
  14. 1. Download Node.js from [nodejs.org](https://nodejs.org/en/download/)
  15. 2. Follow the installation instructions for your operating system
  16. 3. Verify installation by running:
  17. ```sh
  18. npm -v
  19. ```
  20. 4. A version number will be printed if installation was successful
  21. #### Windows Users
  22. - When installing Node.js, use the official installer and make sure the folder is added to PATH when selecting installation options.
  23. ### Install Ahrefs MCP Server
  24. ```sh
  25. npm install --prefix=~/.global-node-modules @ahrefs/mcp -g
  26. ```
  27. ### Upgrading versions
  28. If you've installed our MCP server before, and just want to upgrade, run this command:
  29. ```sh
  30. npm install --prefix=~/.global-node-modules @ahrefs/mcp@latest -g
  31. ```
  32. ## Configuration
  33. You can now add the Ahrefs MCP to your favourite AI assistant app by adding the `ahrefs` part to your app's configuration file:
  34. ```json
  35. {
  36. "mcpServers": {
  37. "ahrefs": {
  38. "command": "npx",
  39. "args": [
  40. "--prefix=~/.global-node-modules",
  41. "@ahrefs/mcp"
  42. ],
  43. "env": {
  44. "API_KEY": "YOUR_API_KEY_HERE"
  45. }
  46. }
  47. }
  48. }
  49. ```
  50. ### Specific for Windows OS
  51. ```json
  52. {
  53. "mcpServers": {
  54. "ahrefs": {
  55. "command": "npx",
  56. "args": [
  57. "--prefix=C:\\Users\\YOUR_USERNAME_HERE\\.global-node-modules\\node_modules",
  58. "@ahrefs/mcp"
  59. ],
  60. "env": {
  61. "API_KEY": "YOUR_API_KEY_HERE"
  62. }
  63. }
  64. }
  65. }
  66. ```
  67. 1. Take note of the double escape backslashes
  68. 2. Take note that the prefix directory is slightly different
  69. 3. Take note of the forward slash for `@ahrefs/mcp`
  70. 4. If you are working with Claude Desktop, run Ctrl-Alt-Del to open Task Manager and kill Claude Desktop. Otherwise, your newly changed config will not be loaded.
  71. To learn more about creating or controlling API keys, refer to the [official documentation](https://docs.ahrefs.com/docs/api/reference/api-keys-creation-and-management).
  72. ### Where to find the configuration file
  73. #### Claude Desktop
  74. 1. Download Claude for Desktop
  75. 2. Select `Settings...`
  76. <p align="center">
  77. <img src="images/claude1.png" alt="Open the Claude menu"/>
  78. </p>
  79. 3. Click on `Developer` in the left panel, then `Edit Config`
  80. <p align="center">
  81. <img src="images/claude2.png" alt="Open the MCP config file"/>
  82. </p>
  83. 4. Paste the configuration [above](#configuration) into the open file
  84. 5. Restart the Claude app! If the installation is successful, it should look like this:
  85. <p align="center">
  86. <img src="images/claude3.png" alt="ahrefs MCP appears under 'tools'"/>
  87. </p>
  88. If you prefer directly navigating to the file, the paths are:
  89. - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
  90. - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
  91. If there are any issues, please refer to the [official documentation](https://modelcontextprotocol.io/quickstart/user)
  92. #### Cursor
  93. Cursor supports configurations that are either project-specific or global: the MCP configuration file will be at `.cursor/mcp.json` or `~/.cursor/mcp.json` respectively.
  94. For more details, read the [official documentation](docs.cursor.com/context/model-context-protocol).
  95. ## Common Installation Issues & Fixes
  96. ### 1. Node.js or npm Not Installed / Recognized
  97. **Symptoms:**
  98. - Running `npm -v` shows an error like `command not found` or `'npm' is not recognized`.
  99. **Fix:**
  100. - Ensure you've installed Node.js from [nodejs.org](https://nodejs.org/en/download/).
  101. - Restart your terminal after installation.
  102. - On **Windows**, make sure the Node.js installer added `npm` to your PATH.
  103. **Platform-Specific Checks:**
  104. - **Windows:**
  105. Open Command Prompt (`Win + R → cmd`) and run:
  106. ```
  107. node -v
  108. npm -v
  109. ```
  110. - **macOS/Linux:**
  111. Open Terminal and run:
  112. ```
  113. which node && which npm
  114. ```
  115. If it returns nothing, Node.js may not be in your `$PATH`.
  116. ---
  117. ### 2. Permission Errors During Global Installation
  118. **Symptoms:**
  119. - Errors like `EACCES: permission denied`, especially on macOS or Linux.
  120. **Fix:**
  121. - Install using a user-scoped global prefix as shown in the installation guide:
  122. ```sh
  123. npm install --prefix=~/.global-node-modules @ahrefs/mcp -g
  124. ```
  125. - This avoids requiring elevated privileges (`sudo`).
  126. **Extra Tip:**
  127. If you used `sudo` previously and created permission issues, reset folder ownership:
  128. ```sh
  129. sudo chown -R $(whoami) ~/.global-node-modules
  130. ```
  131. ### 2a. macOS Terminal Permissions
  132. **Symptoms:**
  133. - Terminal shows "Operation not permitted" errors
  134. - Unable to create folders or files
  135. - Permission denied messages when running npm commands
  136. **Fix:**
  137. Check if Terminal has Full Disk Access:
  138. - Open System Settings (or System Preferences)
  139. - Go to Privacy & Security → Full Disk Access
  140. - Make sure Terminal.app is in the list and checked
  141. - If not present, click '+', navigate to Applications → Utilities → Terminal.app
  142. **Note:**
  143. Modern macOS versions require explicit permissions for Terminal access. Without proper permissions, npm installations and other file operations may fail silently or with permission errors.
  144. ---
  145. ### 3. `npx` Cannot Find the Ahrefs MCP Command
  146. **Symptoms:**
  147. - Error: `Cannot find package '@ahrefs/mcp'`
  148. **Fix:**
  149. Ensure your config uses the same prefix used during install:
  150. ```json
  151. "command": "npx",
  152. "args": [
  153. "--prefix=~/.global-node-modules",
  154. "@ahrefs/mcp"
  155. ]
  156. ```
  157. **Note:**
  158. Do **not** omit the `--prefix` unless you're installing globally system-wide (not recommended).
  159. ---
  160. ### 4. Configuration File Not Detected
  161. **Symptoms:**
  162. - Claude does not list the MCP under “tools”.
  163. **Fix:**
  164. - Make sure the config file path is correct:
  165. - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
  166. - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
  167. - **Linux:** (Rare, but if applicable) `~/.config/Claude/claude_desktop_config.json`
  168. - Double-check you pasted the configuration **inside the correct section** and restarted Claude after saving.
  169. ---
  170. ### 5. API Key Problems
  171. **Symptoms:**
  172. - MCP fails silently or throws an error about `API_KEY`.
  173. - Claude responds with a message that it ran into authentication issues.
  174. **Fix:**
  175. Ensure this line is present in the MCP config:
  176. ```json
  177. "env": {
  178. "API_KEY": "YOUR_API_KEY_HERE"
  179. }
  180. ```
  181. Replace `YOUR_API_KEY_HERE` with your actual key. Ensure that your API key settings give you the necessary permissions.
  182. For more help, refer to [Ahrefs API key docs](https://docs.ahrefs.com/docs/api/reference/api-keys-creation-and-management).
  183. ---
  184. ### 6. Path Expansion Issues
  185. **Symptoms:**
  186. - Error messages containing `ENOENT` or "no such file or directory"
  187. - npm commands fail with path-related errors
  188. - `~` or environment variables not being expanded correctly
  189. **Fix:**
  190. Use absolute paths instead of relying on path expansion:
  191. **Windows:**
  192. ```sh
  193. C:\Users\<username>\.global-node-modules
  194. ```
  195. Replace `<username>` with your actual Windows username.
  196. **macOS:**
  197. ```sh
  198. /Users/<username>/.global-node-modules
  199. ```
  200. Replace `<username>` with your macOS username.
  201. **Linux:**
  202. ```sh
  203. /home/<username>/.global-node-modules
  204. ```
  205. Replace `<username>` with your Linux username.
  206. **Example Configuration:**
  207. ```json
  208. {
  209. "mcpServers": {
  210. "ahrefs": {
  211. "command": "npx",
  212. "args": [
  213. "--prefix=/Users/username/.global-node-modules", // Replace with your absolute path
  214. "@ahrefs/mcp"
  215. ],
  216. "env": {
  217. "API_KEY": "YOUR_API_KEY_HERE"
  218. }
  219. }
  220. }
  221. }
  222. ```
  223. **How to Find Your Absolute Path:**
  224. **Windows:**
  225. 1. Open Command Prompt
  226. 2. Type `echo %USERPROFILE%`
  227. **macOS/Linux:**
  228. 1. Open Terminal
  229. 2. Type `echo $HOME`
  230. **Note:**
  231. Using absolute paths eliminates issues with path expansion and ensures the configuration works regardless of environment variables or shell configurations.
  232. ---
  233. ## 🧪 Diagnostic Commands Per Platform
  234. | Issue | Windows Command | macOS/Linux Command |
  235. |-------|-----------------|---------------------|
  236. | Check Node version | `node -v && npm -v` | `node -v && npm -v` |
  237. | Check if MCP is installed | `npm list -g --prefix=%USERPROFILE%\.global-node-modules @ahrefs/mcp` | `npm list -g --prefix=~/.global-node-modules @ahrefs/mcp`|
  238. | Clear corrupted install | Delete folder manually | `rm -rf ~/.global-node-modules` |
  239. ---
  240. ## 📍 Summary of Key Paths
  241. | Purpose | Windows | macOS | Linux |
  242. |----------|---------|-------|-------|
  243. | Claude config file | `%APPDATA%\Claude\claude_desktop_config.json` | `~/Library/Application Support/Claude/claude_desktop_config.json` | `~/.config/Claude/claude_desktop_config.json` (if applicable) |
  244. | Global MCP install location | `%USERPROFILE%\.global-node-modules` | `~/.global-node-modules` | `~/.global-node-modules` |
  245. ---
  246. ## 📘 Still Having Issues?
  247. - Check the [official MCP documentation](https://modelcontextprotocol.io/quickstart/user)
  248. - Or reach out to internal support at Ahrefs through your usual engineering support channel.
  249. Let us know what errors you're seeing, along with your OS and the output of:
  250. ```sh
  251. npm list -g --prefix=~/.global-node-modules @ahrefs/mcp
  252. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.