https://github.com/ahrefs/ahrefs-mcp-server
Official Ahrefs MCP Server
https://github.com/ahrefs/ahrefs-mcp-server
Last synced: 12 months ago
JSON representation
Official Ahrefs MCP Server
- Host: GitHub
- URL: https://github.com/ahrefs/ahrefs-mcp-server
- Owner: ahrefs
- Created: 2025-04-25T00:24:51.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-05-27T00:20:45.000Z (about 1 year ago)
- Last Synced: 2025-07-22T05:53:45.630Z (about 1 year ago)
- Language: TypeScript
- Homepage:
- Size: 666 KB
- Stars: 34
- Watchers: 24
- Forks: 9
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-seo-mcp-servers - ahrefs-mcp-server
README
# Ahrefs MCP
A Model Context Protocol server to connect Claude desktop and other compatible AI assistants to Ahrefs.
## Installation
`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:
```sh
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
```sh
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:
```sh
npm install --prefix=~/.global-node-modules @ahrefs/mcp@latest -g
```
## Configuration
You can now add the Ahrefs MCP to your favourite AI assistant app by adding the `ahrefs` part to your app's configuration file:
```json
{
"mcpServers": {
"ahrefs": {
"command": "npx",
"args": [
"--prefix=~/.global-node-modules",
"@ahrefs/mcp"
],
"env": {
"API_KEY": "YOUR_API_KEY_HERE"
}
}
}
}
```
### Specific for Windows OS
```json
{
"mcpServers": {
"ahrefs": {
"command": "npx",
"args": [
"--prefix=C:\\Users\\YOUR_USERNAME_HERE\\.global-node-modules\\node_modules",
"@ahrefs/mcp"
],
"env": {
"API_KEY": "YOUR_API_KEY_HERE"
}
}
}
}
```
1. Take note of the double escape backslashes
2. Take note that the prefix directory is slightly different
3. Take note of the forward slash for `@ahrefs/mcp`
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.
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).
### Where to find the configuration file
#### Claude Desktop
1. Download Claude for Desktop
2. Select `Settings...`
3. Click on `Developer` in the left panel, then `Edit Config`
4. Paste the configuration [above](#configuration) into the open file
5. Restart the Claude app! If the installation is successful, it should look like this:
If you prefer directly navigating to the file, the paths are:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
If there are any issues, please refer to the [official documentation](https://modelcontextprotocol.io/quickstart/user)
#### Cursor
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.
For more details, read the [official documentation](docs.cursor.com/context/model-context-protocol).
## Common Installation Issues & Fixes
### 1. Node.js or npm Not Installed / Recognized
**Symptoms:**
- Running `npm -v` shows an error like `command not found` or `'npm' is not recognized`.
**Fix:**
- Ensure you've installed Node.js from [nodejs.org](https://nodejs.org/en/download/).
- Restart your terminal after installation.
- On **Windows**, make sure the Node.js installer added `npm` to your PATH.
**Platform-Specific Checks:**
- **Windows:**
Open Command Prompt (`Win + R → cmd`) and run:
```
node -v
npm -v
```
- **macOS/Linux:**
Open Terminal and run:
```
which node && which npm
```
If it returns nothing, Node.js may not be in your `$PATH`.
---
### 2. Permission Errors During Global Installation
**Symptoms:**
- Errors like `EACCES: permission denied`, especially on macOS or Linux.
**Fix:**
- Install using a user-scoped global prefix as shown in the installation guide:
```sh
npm install --prefix=~/.global-node-modules @ahrefs/mcp -g
```
- This avoids requiring elevated privileges (`sudo`).
**Extra Tip:**
If you used `sudo` previously and created permission issues, reset folder ownership:
```sh
sudo chown -R $(whoami) ~/.global-node-modules
```
### 2a. macOS Terminal Permissions
**Symptoms:**
- Terminal shows "Operation not permitted" errors
- Unable to create folders or files
- Permission denied messages when running npm commands
**Fix:**
Check if Terminal has Full Disk Access:
- Open System Settings (or System Preferences)
- Go to Privacy & Security → Full Disk Access
- Make sure Terminal.app is in the list and checked
- If not present, click '+', navigate to Applications → Utilities → Terminal.app
**Note:**
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.
---
### 3. `npx` Cannot Find the Ahrefs MCP Command
**Symptoms:**
- Error: `Cannot find package '@ahrefs/mcp'`
**Fix:**
Ensure your config uses the same prefix used during install:
```json
"command": "npx",
"args": [
"--prefix=~/.global-node-modules",
"@ahrefs/mcp"
]
```
**Note:**
Do **not** omit the `--prefix` unless you're installing globally system-wide (not recommended).
---
### 4. Configuration File Not Detected
**Symptoms:**
- Claude does not list the MCP under “tools”.
**Fix:**
- Make sure the config file path is correct:
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux:** (Rare, but if applicable) `~/.config/Claude/claude_desktop_config.json`
- Double-check you pasted the configuration **inside the correct section** and restarted Claude after saving.
---
### 5. API Key Problems
**Symptoms:**
- MCP fails silently or throws an error about `API_KEY`.
- Claude responds with a message that it ran into authentication issues.
**Fix:**
Ensure this line is present in the MCP config:
```json
"env": {
"API_KEY": "YOUR_API_KEY_HERE"
}
```
Replace `YOUR_API_KEY_HERE` with your actual key. Ensure that your API key settings give you the necessary permissions.
For more help, refer to [Ahrefs API key docs](https://docs.ahrefs.com/docs/api/reference/api-keys-creation-and-management).
---
### 6. Path Expansion Issues
**Symptoms:**
- Error messages containing `ENOENT` or "no such file or directory"
- npm commands fail with path-related errors
- `~` or environment variables not being expanded correctly
**Fix:**
Use absolute paths instead of relying on path expansion:
**Windows:**
```sh
C:\Users\\.global-node-modules
```
Replace `` with your actual Windows username.
**macOS:**
```sh
/Users//.global-node-modules
```
Replace `` with your macOS username.
**Linux:**
```sh
/home//.global-node-modules
```
Replace `` with your Linux username.
**Example Configuration:**
```json
{
"mcpServers": {
"ahrefs": {
"command": "npx",
"args": [
"--prefix=/Users/username/.global-node-modules", // Replace with your absolute path
"@ahrefs/mcp"
],
"env": {
"API_KEY": "YOUR_API_KEY_HERE"
}
}
}
}
```
**How to Find Your Absolute Path:**
**Windows:**
1. Open Command Prompt
2. Type `echo %USERPROFILE%`
**macOS/Linux:**
1. Open Terminal
2. Type `echo $HOME`
**Note:**
Using absolute paths eliminates issues with path expansion and ensures the configuration works regardless of environment variables or shell configurations.
---
## 🧪 Diagnostic Commands Per Platform
| Issue | Windows Command | macOS/Linux Command |
|-------|-----------------|---------------------|
| Check Node version | `node -v && npm -v` | `node -v && npm -v` |
| Check if MCP is installed | `npm list -g --prefix=%USERPROFILE%\.global-node-modules @ahrefs/mcp` | `npm list -g --prefix=~/.global-node-modules @ahrefs/mcp`|
| Clear corrupted install | Delete folder manually | `rm -rf ~/.global-node-modules` |
---
## 📍 Summary of Key Paths
| Purpose | Windows | macOS | Linux |
|----------|---------|-------|-------|
| 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) |
| Global MCP install location | `%USERPROFILE%\.global-node-modules` | `~/.global-node-modules` | `~/.global-node-modules` |
---
## 📘 Still Having Issues?
- Check the [official MCP documentation](https://modelcontextprotocol.io/quickstart/user)
- Or reach out to internal support at Ahrefs through your usual engineering support channel.
Let us know what errors you're seeing, along with your OS and the output of:
```sh
npm list -g --prefix=~/.global-node-modules @ahrefs/mcp
```