Ahrefs MCP server

Ahrefs MCP is a Model Context Protocol server that connects AI assistants like Claude Desktop to Ahrefs data and functionality. This local server works with API v3 keys and allows your AI assistant to access Ahrefs capabilities directly from your conversations.

Installation Requirements

Install Node.js and npm

1. Download and install 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 during installation.

Install the Ahrefs MCP Server

Run this command in your terminal:

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

Updating to the Latest Version

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

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

Configuration

Add the Ahrefs MCP to your AI assistant app by adding this configuration:

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

Windows Configuration

For Windows users, the configuration requires a slightly different format:

{
    "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, use Task Manager (Ctrl-Alt-Del) to close Claude Desktop completely before restarting

To learn more about API keys, see the official documentation.

Finding and Editing Configuration Files

Claude Desktop

1. Open Claude Desktop
2. Select "Settings..."
3. Click on "Developer" in the left panel, then "Edit Config"
4. Paste the configuration from above
5. Restart Claude Desktop

Configuration file locations:

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

Cursor

Cursor supports either project-specific or global configuration:

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

For more details, see the official Cursor documentation.

Troubleshooting Common Issues

Node.js or npm Not Found

Symptoms:

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

Fix:

• Ensure Node.js is properly installed
• Restart your terminal
• Check if npm is in your PATH

Verification commands:

• Windows: node -v && npm -v
• macOS/Linux: which node && which npm

Permission Errors During Installation

Symptoms:

• Errors like EACCES: permission denied

Fix:

• Use the user-scoped prefix as shown in the installation guide
• If you used sudo previously 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:

• Check Terminal's Full Disk Access:
  1. Open System Settings → Privacy & Security → Full Disk Access
  2. Make sure Terminal.app is in the list and checked
  3. If missing, add it via the "+" button

Package Not Found

Symptoms:

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

Fix:

• Ensure your config uses the same prefix used during installation
• Double-check all path specifications

Configuration File Not Detected

Symptoms:

• Claude doesn't list Ahrefs under "tools"

Fix:

• Verify the config file path is correct
• Ensure the configuration was pasted correctly inside the file
• Restart Claude completely after saving changes

API Key Problems

Symptoms:

• MCP fails silently or throws an authentication error

Fix:

• Make sure your API key is correctly entered in the configuration
• Verify that your API key has the necessary permissions

Path Expansion Issues

Symptoms:

• Error messages containing ENOENT or "no such file or directory"

Fix:

• Use absolute paths instead of relying on path expansion
• Windows example: C:\Users\<username>\.global-node-modules
• macOS example: /Users/<username>/.global-node-modules

Diagnostic Commands

Check Node Version

node -v && npm -v

Verify MCP Installation

Windows:

npm list -g --prefix=%USERPROFILE%\.global-node-modules @ahrefs/mcp

macOS/Linux:

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

If you continue experiencing issues, check the official MCP documentation or contact Ahrefs support.

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