Ahrefs MCP Server

🚀 Ahrefs MCP

Ahrefs MCP 是一个模型上下文协议（Model Context Protocol）服务器，用于将 Claude 桌面应用程序以及其他兼容的 AI 助手连接到 Ahrefs。

🚀 快速开始

✨ 主要特性

• 实现 Claude 桌面端及其他兼容 AI 助手与 Ahrefs 的连接。
• 支持全局安装和版本升级。
• 详细的配置说明，适用于不同操作系统和 AI 应用。

📦 安装指南

npm 命令需要在终端中执行：

• macOS：从“应用程序”文件夹中打开“终端”。
• Windows：按下 Windows + R，输入 cmd，然后按 Enter。

安装 Node.js 和 npm

1. 从 nodejs.org 下载 Node.js。
2. 按照操作系统的安装说明进行操作。
3. 通过运行以下命令验证安装：

npm -v

4. 如果安装成功，将打印出版本号。

Windows 用户注意事项

安装 Node.js 时，请使用官方安装程序，并确保在选择安装选项时将文件夹添加到 PATH 中。

安装 Ahrefs MCP 服务器

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

升级版本

如果您之前已经安装了我们的 MCP 服务器，并且只想进行升级，请运行以下命令：

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

📚 详细文档

配置

您现在可以通过在您喜爱的 AI 助手应用程序的配置文件中添加 ahrefs 部分，将 Ahrefs MCP 添加到该应用程序中：

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

Windows 操作系统特定配置

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

• 注意双反斜杠的使用。
• 注意前缀目录略有不同。
• 注意 @ahrefs/mcp 的斜杠方向。
• 如果您使用的是 Claude Desktop，请按 Ctrl-Alt-Del 打开“任务管理器”，并关闭 Claude Desktop。否则，您新更改的配置将不会加载。

要了解有关创建或控制 API 密钥的更多信息，请参阅 官方文档。

配置文件位置

Claude Desktop

1. 下载适用于桌面的 Claude。
2. 选择 设置...。
3. 点击左侧面板中的 开发者，然后点击 编辑配置。
4. 将 上述配置 粘贴到打开的文件中。
5. 重启 Claude 应用程序！如果安装成功，它应该如下所示：

如果您更喜欢直接导航到文件，路径如下：

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

如果出现任何问题，请参阅 官方文档。

Cursor

Cursor 支持特定于项目或全局的配置：MCP 配置文件将分别位于 .cursor/mcp.json 或 ~/.cursor/mcp.json。 有关更多详细信息，请阅读 官方文档。

🔧 常见安装问题及解决方法

1. Node.js 或 npm 未安装/未被识别

症状：

• 运行 npm -v 显示错误，如 command not found 或 'npm' is not recognized。

解决方法：

• 确保您已从 nodejs.org 安装了 Node.js。
• 安装后重启终端。
• 在 Windows 上，确保 Node.js 安装程序将 npm 添加到了您的 PATH 中。

特定平台检查：

• Windows： 打开命令提示符（Win + R → cmd）并运行：

  node -v
  npm -v
  

• macOS/Linux： 打开终端并运行：

  which node && which npm
  

如果没有返回任何内容，则 Node.js 可能不在您的 $PATH 中。

2. 全局安装期间的权限错误

症状：

• 出现 EACCES: permission denied 等错误，尤其是在 macOS 或 Linux 上。

解决方法：

• 按照安装指南中所示，使用用户范围的全局前缀进行安装：

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

• 这样可以避免需要提升权限（sudo）。

额外提示： 如果您之前使用了 sudo 并导致了权限问题，请重置文件夹所有权：

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

2a. macOS 终端权限问题

症状：

• 终端显示 “Operation not permitted” 错误。
• 无法创建文件夹或文件。
• 运行 npm 命令时出现权限被拒绝的消息。

解决方法： 检查终端是否具有“完全磁盘访问权限”：

• 打开“系统设置”（或“系统偏好设置”）。
• 转到“隐私与安全” → “完全磁盘访问”。
• 确保“终端.app”在列表中并已勾选。
• 如果不存在，请点击 +，导航到“应用程序” → “实用工具” → “终端.app”。

注意： 现代 macOS 版本要求终端具有明确的访问权限。如果没有适当的权限，npm 安装和其他文件操作可能会无声失败或出现权限错误。

3. npx 找不到 Ahrefs MCP 命令

症状：

• 错误：Cannot find package '@ahrefs/mcp'。

解决方法： 确保您的配置使用了安装期间使用的相同前缀：

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

注意： 除非您要在系统范围内全局安装（不推荐），否则不要省略 --prefix。

4. 配置文件未被检测到

症状：

• Claude 在“工具”下列表中未显示 MCP。

解决方法：

• 确保配置文件路径正确：
  • Windows：%APPDATA%\Claude\claude_desktop_config.json
  • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
  • Linux：（很少见，但如果适用）~/.config/Claude/claude_desktop_config.json
• 仔细检查您是否将配置粘贴到了 正确的部分，并在保存后重启了 Claude。

5. API 密钥问题

症状：

• MCP 无声失败或抛出有关 API_KEY 的错误。
• Claude 响应有关身份验证问题的消息。

解决方法： 确保 MCP 配置中存在以下行：

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

将 YOUR_API_KEY_HERE 替换为您的实际密钥。确保您的 API 密钥设置赋予了您必要的权限。

有关更多帮助，请参阅 Ahrefs API 密钥文档。

6. 路径扩展问题

症状：

• 错误消息包含 ENOENT 或 “no such file or directory”。
• npm 命令因路径相关错误而失败。
• ~ 或环境变量未正确扩展。

解决方法： 使用绝对路径而不是依赖路径扩展：

Windows：

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

将 <username> 替换为您的实际 Windows 用户名。

macOS：

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

将 <username> 替换为您的 macOS 用户名。

Linux：

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

将 <username> 替换为您的 Linux 用户名。

示例配置：

{
    "mcpServers": {
        "ahrefs": {
            "command": "npx",
            "args": [
                "--prefix=/Users/username/.global-node-modules",  // 替换为您的绝对路径
                "@ahrefs/mcp"
            ],
            "env": {
                "API_KEY": "YOUR_API_KEY_HERE"
            }
        }
    }
}

如何查找您的绝对路径：

Windows：

1. 打开命令提示符。
2. 输入 echo %USERPROFILE%。

macOS/Linux：

1. 打开终端。
2. 输入 echo $HOME。

注意： 使用绝对路径可以消除路径扩展问题，并确保配置在任何环境变量或 shell 配置下都能正常工作。

📋 各平台诊断命令

📍 关键路径总结

📘 仍然有问题？

• 查看 官方 MCP 文档。
• 或者通过您通常的工程支持渠道联系 Ahrefs 的内部支持团队。

请告知我们您遇到的错误，以及您的操作系统和以下命令的输出：

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