Ahrefs MCP Server

🚀 Ahrefs MCP

Ahrefs MCPは、Claudeデスクトップやその他の互換性のあるAIアシスタントをAhrefsに接続するためのモデルコンテキストプロトコルサーバーです。

🚀 クイックスタート

📦 インストール

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 OS用の設定

{
    "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 Desktopを使用している場合は、Ctrl-Alt-Delを押してタスクマネージャーを開き、Claude Desktopを終了します。そうしないと、新しく変更した設定が読み込まれません。

APIキーの作成や管理について詳しくは、公式ドキュメントを参照してください。

設定ファイルの場所

Claude Desktop

1. Claude for Desktopをダウンロードします。
2. Settings...を選択します。
3. 左パネルのDeveloperをクリックし、Edit Configをクリックします。
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コマンドを実行するとパーミッション拒否のメッセージが表示されます。

解決策: ターミナルがフルディスクアクセスを持っていることを確認します。

• システム設定（またはシステム環境設定）を開きます。
• プライバシーとセキュリティ → フルディスクアクセスに移動します。
• Terminal.appがリストにあり、チェックされていることを確認します。
• 存在しない場合は、「+」をクリックし、アプリケーション → ユーティリティ → Terminal.appに移動します。

注意: 最新のmacOSバージョンでは、ターミナルアクセスに明示的なパーミッションが必要です。適切なパーミッションがないと、npmインストールやその他のファイル操作がサイレントに失敗するか、パーミッションエラーが発生する可能性があります。

3. npxがAhrefs MCPコマンドを見つけられない

症状:

• エラー: Cannot find package '@ahrefs/mcp'

解決策: 設定でインストール時に使用したのと同じプレフィックスを使用することを確認します。

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

注意: グローバルにシステム全体にインストールする場合（推奨されません）を除き、--prefixを省略しないでください。

4. 設定ファイルが検出されない

症状:

• Claudeが「tools」の下に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と入力します。

注意: 絶対パスを使用することで、パス展開に関する問題が解消され、環境変数やシェル設定に関係なく設定が機能することが保証されます。

🧪 プラットフォーム別診断コマンド

📍 主要パスのまとめ

📘 依然として問題がある場合

• 公式MCPドキュメントを確認してください。
• または、通常のエンジニアリングサポートチャネルを通じてAhrefsの内部サポートに問い合わせてください。

エラー内容、使用しているOS、および以下のコマンドの出力を教えてください。

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