Ahrefs MCP Server

How to use

Set up the local MCP server and configure your client to load the Ahrefs MCP as a tool. You will provide the API key to authenticate with Ahrefs, then load the MCP into your assistant app through its MCP configuration. Once configured, you can ask your assistant to fetch Ahrefs data, run analyses, or perform actions that rely on Ahrefs APIs. Ensure your client loads the Ahrefs MCP using the exact command and environment variables shown in the configuration examples, and restart the client after saving changes.

How to install

Prerequisites: you need Node.js and npm. Install Node.js from nodejs.org, then verify the installation by printing version numbers.

node -v
npm -v

Install the Ahrefs MCP Server globally for your user, avoiding elevated privileges.

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

If you have previously installed the MCP server and want to upgrade to the latest version, run this command.

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

Windows users should ensure the Node.js installer adds Node and npm to PATH during installation. Use the official installer and verify PATH inclusion.

Configuration

Configure your AI assistant to load the Ahrefs MCP by adding the following MCP configuration. This config uses npx to run the MCP from the global modules location and requires an API key for Ahrefs access.

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

Specific for Windows OS

Windows users should adjust the prefix path to a Windows-style path. Use the Windows-specific example when adding the MCP to your client configuration.

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

Where to place the configuration

Load the configuration into your chosen client (Claude Desktop or Cursor) and restart the client to apply changes. Use the provided paths and keys exactly as shown in the examples.

Claude Desktop and Cursor each have their own steps to reach the configuration area. After pasting the MCP config, restart the app to ensure the MCP is loaded.

Common installation issues & fixes

If you encounter problems, verify Node.js and npm are installed and available in your PATH. On Windows, run node -v and npm -v to confirm. On macOS or Linux, run which node and which npm to confirm their locations.

If you receive permission errors during global installation, use the user-scoped global prefix shown in the installation steps and avoid sudo. If permissions were previously changed, reset ownership of the ~/.global-node-modules directory.

If the MCP command cannot be found, ensure your config uses the same --prefix value as during install and that the package name is included in the args.

If the MCP configuration is not detected by your client, confirm the configuration file path for your platform and ensure the MCP config is placed in the correct section of the client’s config file, then restart the client.

API key problems can prevent authentication. Ensure the API_KEY is present in the MCP config and points to a valid key with necessary permissions.

Path expansion issues can cause ENOENT errors. Use absolute paths for the --prefix value in Windows, macOS, and Linux examples.

Diagnostic commands and tips

If issues persist, gather diagnostic information by listing globally installed MCP packages and confirming their paths.

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