This is page 1 of 2. Use http://codebase.md/ahrefs/ahrefs-mcp-server?lines=true&page={x} to view the full context.
# Directory Structure
```
├── .gitignore
├── images
│ ├── claude1.png
│ ├── claude2.png
│ └── claude3.png
├── mcp.json
├── package-lock.json
├── package.json
├── README.md
├── src
│ ├── index.ts
│ ├── server.ts
│ └── transport.ts
└── tsconfig.json
```
# Files
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
1 | node_modules/
2 | dist/
3 | build/
4 | .env
5 | .DS_Store
```
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
```markdown
1 | > [!NOTE]
2 | > This repository is for the **local Ahrefs MCP server** which works with API v3 keys only. It **DOES NOT** work with MCP keys. We've also released a **remote Ahrefs MCP server**, which doesn't require local setup and works directly in popular AI tools.
3 | >
4 | > Learn more here: [Remote MCP server documentation](https://docs.ahrefs.com/docs/mcp/reference/introduction)
5 |
6 | # Ahrefs MCP
7 | A Model Context Protocol server to connect Claude desktop and other compatible AI assistants to Ahrefs.
8 |
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 |
22 | #### Windows Users
23 | - When installing Node.js, use the official installer and make sure the folder is added to PATH when selecting installation options.
24 |
25 | ### Install Ahrefs MCP Server
26 | ```sh
27 | npm install --prefix=~/.global-node-modules @ahrefs/mcp -g
28 | ```
29 | ### Upgrading versions
30 | If you've installed our MCP server before, and just want to upgrade, run this command:
31 | ```sh
32 | npm install --prefix=~/.global-node-modules @ahrefs/mcp@latest -g
33 | ```
34 |
35 | ## Configuration
36 | You can now add the Ahrefs MCP to your favourite AI assistant app by adding the `ahrefs` part to your app's configuration file:
37 | ```json
38 | {
39 | "mcpServers": {
40 | "ahrefs": {
41 | "command": "npx",
42 | "args": [
43 | "--prefix=~/.global-node-modules",
44 | "@ahrefs/mcp"
45 | ],
46 | "env": {
47 | "API_KEY": "YOUR_API_KEY_HERE"
48 | }
49 | }
50 | }
51 | }
52 | ```
53 |
54 | ### Specific for Windows OS
55 | ```json
56 | {
57 | "mcpServers": {
58 | "ahrefs": {
59 | "command": "npx",
60 | "args": [
61 | "--prefix=C:\\Users\\YOUR_USERNAME_HERE\\.global-node-modules\\node_modules",
62 | "@ahrefs/mcp"
63 | ],
64 | "env": {
65 | "API_KEY": "YOUR_API_KEY_HERE"
66 | }
67 | }
68 | }
69 | }
70 | ```
71 | 1. Take note of the double escape backslashes
72 | 2. Take note that the prefix directory is slightly different
73 | 3. Take note of the forward slash for `@ahrefs/mcp`
74 | 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.
75 |
76 | 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).
77 | ### Where to find the configuration file
78 | #### Claude Desktop
79 | 1. Download Claude for Desktop
80 | 2. Select `Settings...`
81 |
82 | <p align="center">
83 | <img src="images/claude1.png" alt="Open the Claude menu"/>
84 | </p>
85 |
86 | 3. Click on `Developer` in the left panel, then `Edit Config`
87 |
88 | <p align="center">
89 | <img src="images/claude2.png" alt="Open the MCP config file"/>
90 | </p>
91 |
92 | 4. Paste the configuration [above](#configuration) into the open file
93 |
94 | 5. Restart the Claude app! If the installation is successful, it should look like this:
95 |
96 | <p align="center">
97 | <img src="images/claude3.png" alt="ahrefs MCP appears under 'tools'"/>
98 | </p>
99 |
100 | If you prefer directly navigating to the file, the paths are:
101 | - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
102 | - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
103 |
104 | If there are any issues, please refer to the [official documentation](https://modelcontextprotocol.io/quickstart/user)
105 | #### Cursor
106 | 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.
107 | For more details, read the [official documentation](docs.cursor.com/context/model-context-protocol).
108 |
109 | ## Common Installation Issues & Fixes
110 |
111 | ### 1. Node.js or npm Not Installed / Recognized
112 |
113 | **Symptoms:**
114 | - Running `npm -v` shows an error like `command not found` or `'npm' is not recognized`.
115 |
116 | **Fix:**
117 | - Ensure you've installed Node.js from [nodejs.org](https://nodejs.org/en/download/).
118 | - Restart your terminal after installation.
119 | - On **Windows**, make sure the Node.js installer added `npm` to your PATH.
120 |
121 | **Platform-Specific Checks:**
122 | - **Windows:**
123 | Open Command Prompt (`Win + R → cmd`) and run:
124 | ```
125 | node -v
126 | npm -v
127 | ```
128 | - **macOS/Linux:**
129 | Open Terminal and run:
130 | ```
131 | which node && which npm
132 | ```
133 | If it returns nothing, Node.js may not be in your `$PATH`.
134 |
135 | ---
136 |
137 | ### 2. Permission Errors During Global Installation
138 |
139 | **Symptoms:**
140 | - Errors like `EACCES: permission denied`, especially on macOS or Linux.
141 |
142 | **Fix:**
143 | - Install using a user-scoped global prefix as shown in the installation guide:
144 | ```sh
145 | npm install --prefix=~/.global-node-modules @ahrefs/mcp -g
146 | ```
147 | - This avoids requiring elevated privileges (`sudo`).
148 |
149 | **Extra Tip:**
150 | If you used `sudo` previously and created permission issues, reset folder ownership:
151 | ```sh
152 | sudo chown -R $(whoami) ~/.global-node-modules
153 | ```
154 | ### 2a. macOS Terminal Permissions
155 |
156 | **Symptoms:**
157 | - Terminal shows "Operation not permitted" errors
158 | - Unable to create folders or files
159 | - Permission denied messages when running npm commands
160 |
161 | **Fix:**
162 | Check if Terminal has Full Disk Access:
163 | - Open System Settings (or System Preferences)
164 | - Go to Privacy & Security → Full Disk Access
165 | - Make sure Terminal.app is in the list and checked
166 | - If not present, click '+', navigate to Applications → Utilities → Terminal.app
167 |
168 | **Note:**
169 | 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.
170 |
171 | ---
172 |
173 | ### 3. `npx` Cannot Find the Ahrefs MCP Command
174 |
175 | **Symptoms:**
176 | - Error: `Cannot find package '@ahrefs/mcp'`
177 |
178 | **Fix:**
179 | Ensure your config uses the same prefix used during install:
180 | ```json
181 | "command": "npx",
182 | "args": [
183 | "--prefix=~/.global-node-modules",
184 | "@ahrefs/mcp"
185 | ]
186 | ```
187 |
188 | **Note:**
189 | Do **not** omit the `--prefix` unless you're installing globally system-wide (not recommended).
190 |
191 | ---
192 |
193 | ### 4. Configuration File Not Detected
194 |
195 | **Symptoms:**
196 | - Claude does not list the MCP under “tools”.
197 |
198 | **Fix:**
199 | - Make sure the config file path is correct:
200 | - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
201 | - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
202 | - **Linux:** (Rare, but if applicable) `~/.config/Claude/claude_desktop_config.json`
203 | - Double-check you pasted the configuration **inside the correct section** and restarted Claude after saving.
204 |
205 | ---
206 |
207 | ### 5. API Key Problems
208 |
209 | **Symptoms:**
210 | - MCP fails silently or throws an error about `API_KEY`.
211 | - Claude responds with a message that it ran into authentication issues.
212 |
213 | **Fix:**
214 | Ensure this line is present in the MCP config:
215 | ```json
216 | "env": {
217 | "API_KEY": "YOUR_API_KEY_HERE"
218 | }
219 | ```
220 | Replace `YOUR_API_KEY_HERE` with your actual key. Ensure that your API key settings give you the necessary permissions.
221 |
222 | For more help, refer to [Ahrefs API key docs](https://docs.ahrefs.com/docs/api/reference/api-keys-creation-and-management).
223 |
224 | ---
225 |
226 | ### 6. Path Expansion Issues
227 |
228 | **Symptoms:**
229 | - Error messages containing `ENOENT` or "no such file or directory"
230 | - npm commands fail with path-related errors
231 | - `~` or environment variables not being expanded correctly
232 |
233 | **Fix:**
234 | Use absolute paths instead of relying on path expansion:
235 |
236 | **Windows:**
237 | ```sh
238 | C:\Users\<username>\.global-node-modules
239 | ```
240 | Replace `<username>` with your actual Windows username.
241 |
242 | **macOS:**
243 | ```sh
244 | /Users/<username>/.global-node-modules
245 | ```
246 | Replace `<username>` with your macOS username.
247 |
248 | **Linux:**
249 | ```sh
250 | /home/<username>/.global-node-modules
251 | ```
252 | Replace `<username>` with your Linux username.
253 |
254 | **Example Configuration:**
255 | ```json
256 | {
257 | "mcpServers": {
258 | "ahrefs": {
259 | "command": "npx",
260 | "args": [
261 | "--prefix=/Users/username/.global-node-modules", // Replace with your absolute path
262 | "@ahrefs/mcp"
263 | ],
264 | "env": {
265 | "API_KEY": "YOUR_API_KEY_HERE"
266 | }
267 | }
268 | }
269 | }
270 | ```
271 |
272 | **How to Find Your Absolute Path:**
273 |
274 | **Windows:**
275 | 1. Open Command Prompt
276 | 2. Type `echo %USERPROFILE%`
277 |
278 | **macOS/Linux:**
279 | 1. Open Terminal
280 | 2. Type `echo $HOME`
281 |
282 | **Note:**
283 | Using absolute paths eliminates issues with path expansion and ensures the configuration works regardless of environment variables or shell configurations.
284 |
285 | ---
286 |
287 | ## 🧪 Diagnostic Commands Per Platform
288 |
289 | | Issue | Windows Command | macOS/Linux Command |
290 | |-------|-----------------|---------------------|
291 | | Check Node version | `node -v && npm -v` | `node -v && npm -v` |
292 | | Check if MCP is installed | `npm list -g --prefix=%USERPROFILE%\.global-node-modules @ahrefs/mcp` | `npm list -g --prefix=~/.global-node-modules @ahrefs/mcp`|
293 | | Clear corrupted install | Delete folder manually | `rm -rf ~/.global-node-modules` |
294 |
295 | ---
296 |
297 | ## 📍 Summary of Key Paths
298 |
299 | | Purpose | Windows | macOS | Linux |
300 | |----------|---------|-------|-------|
301 | | 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) |
302 | | Global MCP install location | `%USERPROFILE%\.global-node-modules` | `~/.global-node-modules` | `~/.global-node-modules` |
303 |
304 | ---
305 |
306 | ## 📘 Still Having Issues?
307 |
308 | - Check the [official MCP documentation](https://modelcontextprotocol.io/quickstart/user)
309 | - Or reach out to internal support at Ahrefs through your usual engineering support channel.
310 |
311 | Let us know what errors you're seeing, along with your OS and the output of:
312 | ```sh
313 | npm list -g --prefix=~/.global-node-modules @ahrefs/mcp
314 | ```
315 |
```
--------------------------------------------------------------------------------
/src/index.ts:
--------------------------------------------------------------------------------
```typescript
1 | #!/usr/bin/env node
2 | import './transport.js';
```
--------------------------------------------------------------------------------
/mcp.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "mcpServers": {
3 | "ahrefs": {
4 | "command": "npx",
5 | "args": [
6 | "@ahrefs/mcp"
7 | ],
8 | "env": {
9 | "API_KEY": "YOUR_API_KEY_HERE"
10 | }
11 | }
12 | }
13 | }
```
--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "compilerOptions": {
3 | "esModuleInterop": true,
4 | "skipLibCheck": true,
5 | "target": "ES2022",
6 | "allowJs": true,
7 | "resolveJsonModule": true,
8 | "moduleDetection": "force",
9 | "isolatedModules": true,
10 | "strict": true,
11 | "noUncheckedIndexedAccess": true,
12 | "noImplicitAny": true,
13 | "strictNullChecks": true,
14 | "strictFunctionTypes": true,
15 | "strictBindCallApply": true,
16 | "strictPropertyInitialization": true,
17 | "noImplicitThis": true,
18 | "alwaysStrict": true,
19 | "module": "NodeNext",
20 | "outDir": "build",
21 | "sourceMap": true,
22 | "lib": ["es2022"]
23 | },
24 | "include": ["src/**/*"],
25 | "exclude": ["node_modules", "build"]
26 | }
```
--------------------------------------------------------------------------------
/src/transport.ts:
--------------------------------------------------------------------------------
```typescript
1 | import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
2 | import { OpenApiMcpServer } from './server.js';
3 | import * as console from 'console';
4 |
5 | console.error("Starting STDIO transport");
6 | const serverInstance = new OpenApiMcpServer();
7 | const stdioTransport = new StdioServerTransport();
8 |
9 | // Connect the server instance to the transport
10 | serverInstance.server.connect(stdioTransport)
11 | .then(() => {
12 | console.error("MCP server connected via STDIO and running.");
13 | console.error("MCP_SERVER_READY");
14 | })
15 | .catch(error => {
16 | console.error("Failed to connect MCP server via STDIO:", error);
17 | process.exit(1);
18 | });
```
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "name": "@ahrefs/mcp",
3 | "version": "0.0.11",
4 | "description": "Ahrefs MCP server",
5 | "main": "build/index.js",
6 | "type": "module",
7 | "scripts": {
8 | "build": "tsc",
9 | "start": "npm run build && node build/index.js"
10 | },
11 | "keywords": [
12 | "mcp",
13 | "model-context-protocol",
14 | "openapi",
15 | "ahrefs"
16 | ],
17 | "bin": {
18 | "mcp": "build/index.js"
19 | },
20 | "author": "Ahrefs",
21 | "license": "MIT",
22 | "files": [
23 | "build/"
24 | ],
25 | "dependencies": {
26 | "@modelcontextprotocol/sdk": "^1.8.0",
27 | "axios": "^1.8.0"
28 | },
29 | "devDependencies": {
30 | "@types/node": "^22.13.0",
31 | "typescript": "^5.7.0"
32 | }
33 | }
34 |
```