The Ahrefs MCP Server connects AI assistants like Claude to Ahrefs' comprehensive SEO and analytics platform, enabling data retrieval and analysis across multiple domains.
Core Capabilities:
Rank Tracking: Monitor keyword rankings, positions, traffic, and competitor performance with historical comparisons and device-specific filtering
Keywords Explorer: Research search volume, CPC, difficulty, traffic potential, intent, matching terms, related keywords, and search suggestions
Site Explorer: Analyze domain/URL ratings, backlinks, referring domains, anchors, internal/external links, and organic keywords with historical data
Backlink Analysis: Retrieve comprehensive data on all backlinks, broken links, referring domains, and anchor texts with aggregation options
SERP Overview: View detailed search results metrics for specific keywords and countries, including top positions and traffic data
Batch Analysis: Perform bulk analysis of multiple URLs, domains, or subdomains for SEO metrics, backlinks, and organic/paid traffic
Site Audit: Access available site audit projects and retrieve audit data
Page Analysis: Identify top-performing pages by organic traffic or links, analyze paid search results with detailed SEO metrics
Project Management: Access project details, keywords, locations, competitors, and management data associated with Ahrefs accounts
All functions support filtering, historical data analysis, country-specific breakdowns, and include full documentation for understanding input schemas and capabilities.
Provides runtime environment for the Ahrefs MCP server, enabling connection between AI assistants and Ahrefs SEO platform
Used for installing and managing the Ahrefs MCP server package
This repository is for thelocal 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
Download Node.js from nodejs.org
Follow the installation instructions for your operating system
Verify installation by running:
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
Upgrading versions
If you've installed our MCP server before, and just want to upgrade, run this command:
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:
Specific for Windows OS
Take note of the double escape backslashes
Take note that the prefix directory is slightly different
Take note of the forward slash for
@ahrefs/mcp
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
Download Claude for Desktop
Select
Settings...
Click on
Developer
in the left panel, thenEdit Config
Paste the configuration above into the open file
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 likecommand 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 -vmacOS/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 -gThis avoids requiring elevated privileges (
sudo
).
Extra Tip:
If you used sudo
previously and created permission issues, reset folder ownership:
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:
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:
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:
Replace <username>
with your actual Windows username.
macOS:
Replace <username>
with your macOS username.
Linux:
Replace <username>
with your Linux username.
Example Configuration:
How to Find Your Absolute Path:
Windows:
Open Command Prompt
Type
echo %USERPROFILE%
macOS/Linux:
Open Terminal
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 |
|
|
Check if MCP is installed |
|
|
Clear corrupted install | Delete folder manually |
|
📍 Summary of Key Paths
Purpose | Windows | macOS | Linux |
Claude config file |
|
|
(if applicable) |
Global MCP install location |
|
|
|
📘 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:
local-only server
The server can only run on the client's local machine because it depends on local resources.
Tools
A Model Context Protocol server that connects Claude desktop and other compatible AI assistants to Ahrefs, allowing them to access Ahrefs functionality.
Related MCP Servers
- -securityFlicense-qualityA comprehensive suite of Model Context Protocol servers designed to extend AI agent Claude's capabilities with integrations for knowledge management, reasoning, advanced search, news access, and workspace tools.Last updated -5
- AsecurityFlicenseAqualityA Model Context Protocol server that connects Claude and other AI assistants to your Notion workspace, allowing AIs to interact with databases, pages, and blocks.Last updated -12011
- AsecurityAlicenseAqualityA Model Context Protocol server that enables AI assistants like Claude to interact directly with Home Assistant, allowing them to query device states, control smart home entities, and perform automation tasks.Last updated -12191MIT License
- -securityFlicense-qualityA Model Context Protocol server that extends AI capabilities by providing file system access and management functionalities to Claude or other AI assistants.Last updated -4186