Note

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.

Learn more here: Remote MCP server documentation

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
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

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:

{
    "mcpServers": {
        "ahrefs": {
            "command": "npx",
            "args": [
                "--prefix=~/.global-node-modules",
                "@ahrefs/mcp"
            ],
            "env": {
                "API_KEY": "YOUR_API_KEY_HERE"
            }
        }
    }
}

Specific for Windows OS

{
    "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.

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 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

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.

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.
• 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:

  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:

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:

"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:

"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.

---

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:

C:\Users\<username>\.global-node-modules

Replace <username> with your actual Windows username.

macOS:

/Users/<username>/.global-node-modules

Replace <username> with your macOS username.

Linux:

/home/<username>/.global-node-modules

Replace <username> with your Linux username.

Example Configuration:

{
    "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
• 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:

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