Ahrefs MCP server

The Ahrefs MCP server allows you to connect Claude desktop and other compatible AI assistants to Ahrefs data and functionality through the Model Context Protocol standard. This integration empowers your AI assistant to directly access Ahrefs features when you need them.

Installation

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

When installing Node.js on Windows, use the official installer and ensure the folder is added to PATH when selecting installation options.

Install Ahrefs MCP Server

Run this command in your terminal:

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

Upgrading to a Newer Version

If you've previously installed the MCP server and want to upgrade:

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

Configuration

Adding Ahrefs MCP to Your AI Assistant

Add the following to your AI assistant's configuration file:

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

Windows Configuration

For Windows users, use this configuration instead:

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

Important Windows notes:

• Use double backslashes in file paths
• The prefix directory structure is slightly different
• Use forward slash for @ahrefs/mcp
• After changing the config, restart Claude Desktop completely (use Task Manager to close it if needed)

Finding Your API Key

For information about creating or managing API keys, refer to the official Ahrefs API documentation.

Locating Configuration Files

Claude Desktop

1. Open Claude Desktop
2. Go to Settings
3. Click on Developer in the left panel, then Edit Config
4. Paste the configuration into the file
5. Restart Claude

Direct file paths:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

For additional help, see the official MCP documentation.

Cursor

Cursor supports both project-specific and global configurations:

• Project-specific: .cursor/mcp.json
• Global: ~/.cursor/mcp.json

For more details, see Cursor's documentation.

Troubleshooting Common Issues

Node.js or npm Not Installed

Symptoms:

• npm -v shows errors like command not found or 'npm' is not recognized

Fix:

• Ensure Node.js is installed from nodejs.org
• Restart your terminal after installation
• Verify installation with:

Windows:

node -v
npm -v

macOS/Linux:

which node && which npm

Permission Errors

Symptoms:

• Errors like EACCES: permission denied

Fix:

• Use the user-scoped global prefix as shown in the installation guide:

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

If you previously used sudo and created permission issues:

sudo chown -R $(whoami) ~/.global-node-modules

macOS Terminal Permissions

Symptoms:

• "Operation not permitted" errors
• Unable to create folders or files

Fix:

• Give Terminal Full Disk Access:
  1. Open System Settings
  2. Go to Privacy & Security → Full Disk Access
  3. Ensure Terminal.app is in the list and checked

Package Not Found

Symptoms:

• Error: Cannot find package '@ahrefs/mcp'

Fix:

• Ensure your config uses the same prefix used during installation:

"command": "npx",
"args": [
    "--prefix=~/.global-node-modules",
    "@ahrefs/mcp"
]

Configuration File Not Detected

Symptoms:

• Claude doesn't list Ahrefs under "tools"

Fix:

• Verify config file path is correct
• Ensure you pasted the configuration in the correct section
• Restart Claude after saving changes

API Key Problems

Symptoms:

• MCP fails silently or shows authentication errors

Fix:

• Make sure your API key is correctly specified:

"env": {
  "API_KEY": "YOUR_API_KEY_HERE"
}

Path Expansion Issues

Symptoms:

• Errors containing ENOENT or "no such file or directory"

Fix:

• Use absolute paths instead of relying on path expansion:

Windows:

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

macOS:

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

Linux:

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

To find your absolute path:

Windows: Run echo %USERPROFILE% in Command Prompt macOS/Linux: Run echo $HOME in Terminal

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

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

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect