Ahrefs MCP Server

🚀 Ahrefs MCP

Ahrefs MCP 是一個模型上下文協議（MCP）服務器，用於將 Claude 桌面端及其他兼容的 AI 助手連接到 Ahrefs。

🚀 快速開始

你可以按照以下步驟完成 Ahrefs MCP 的安裝和配置：

1. 安裝 Node.js 和 npm
2. 安裝 Ahrefs MCP 服務器
3. 配置 AI 助手應用

✨ 主要特性

• 連接性：能夠將 Claude 桌面端及其他兼容的 AI 助手連接到 Ahrefs。
• 可配置性：可以通過修改配置文件來集成到不同的 AI 助手應用中。

📦 安裝指南

npm 命令需要在終端中執行：

• macOS：從“應用程序”文件夾中打開“終端”。
• Windows：按下 Windows + R，輸入 cmd，然後按回車鍵。

安裝 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

📚 詳細文檔

配置

你可以通過在應用的配置文件中添加 ahrefs 部分，將 Ahrefs MCP 添加到你喜歡的 AI 助手應用中：

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

1. 注意使用雙反斜槓進行轉義。
2. 注意前綴目錄略有不同。
3. 注意 @ahrefs/mcp 使用正斜槓。
4. 如果你使用的是 Claude 桌面端，請按下 Ctrl + Alt + Del 打開“任務管理器”，並關閉 Claude 桌面端。否則，新更改的配置將不會加載。

若要了解更多關於創建或管理 API 密鑰的信息，請參考 官方文檔。

配置文件位置

Claude 桌面端

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 終端權限問題

症狀：

• 終端顯示“操作不允許”錯誤。
• 無法創建文件夾或文件。
• 運行 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 密鑰。確保你的 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