ahrefs-mcp-server
Official Ahrefs MCP Server
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/ahrefs--ahrefs-mcp-server)HTML
<a href="/listings/ahrefs--ahrefs-mcp-server"><img src="/api/listings/ahrefs--ahrefs-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
`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](https://nodejs.org/en/download/) 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
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 316 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- > [!WARNING]
- > This repository is no longer maintained!
- > We have 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](https://docs.ahrefs.com/docs/mcp/reference/introduction)
- >
- > This repository is for the **local Ahrefs MCP server** which works with API v3 keys only. It **DOES NOT** work with MCP keys. It **IS NOT** maintained. It is **OUTDATED**. And we do not recommend using it.
- # 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](https://nodejs.org/en/download/)
- 2. Follow the installation instructions for your operating system
- 3. Verify installation by running:
- ```sh
- 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
- ```sh
- 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:
- ```sh
- 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:
- ```json
- {
- "mcpServers": {
- "ahrefs": {
- "command": "npx",
- "args": [
- "--prefix=~/.global-node-modules",
- "@ahrefs/mcp"
- ],
- "env": {
- "API_KEY": "YOUR_API_KEY_HERE"
- }
- }
- }
- }
- ```
- ### Specific for Windows OS
- ```json
- {
- "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](https://docs.ahrefs.com/docs/api/reference/api-keys-creation-and-management).
- ### Where to find the configuration file
- #### Claude Desktop
- 1. Download Claude for Desktop
- 2. Select `Settings...`
- <p align="center">
- <img src="images/claude1.png" alt="Open the Claude menu"/>
- </p>
- 3. Click on `Developer` in the left panel, then `Edit Config`
- <p align="center">
- <img src="images/claude2.png" alt="Open the MCP config file"/>
- </p>
- 4. Paste the configuration [above](#configuration) into the open file
- 5. Restart the Claude app! If the installation is successful, it should look like this:
- <p align="center">
- <img src="images/claude3.png" alt="ahrefs MCP appears under 'tools'"/>
- </p>
- 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](https://modelcontextprotocol.io/quickstart/user)
- #### 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](docs.cursor.com/context/model-context-protocol).
- ## 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](https://nodejs.org/en/download/).
- - 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:
- ```sh
- 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:
- ```sh
- 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:
- ```json
- "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:
- ```json
- "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](https://docs.ahrefs.com/docs/api/reference/api-keys-creation-and-management).
- ---
- ### 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:**
- ```sh
- C:\Users\<username>\.global-node-modules
- ```
- Replace `<username>` with your actual Windows username.
- **macOS:**
- ```sh
- /Users/<username>/.global-node-modules
- ```
- Replace `<username>` with your macOS username.
- **Linux:**
- ```sh
- /home/<username>/.global-node-modules
- ```
- Replace `<username>` with your Linux username.
- **Example Configuration:**
- ```json
- {
- "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](https://modelcontextprotocol.io/quickstart/user)
- - 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:
- ```sh
- npm list -g --prefix=~/.global-node-modules @ahrefs/mcp
- ```
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.