Google Search Console Mcp Server

Google Search Console MCP サーバー

Claude Code と Cursor を通じて、Google Search Console API のデータへプログラムからアクセスできる Model Context Protocol（MCP）サーバーです。

クイックスタート

この MCP サーバーを初めて使いますか？ 詳細な手順については、ステップバイステップのセットアップガイドをご覧ください。

機能

• 🔍 サイト一覧 - アクセス権のある Search Console のプロパティをすべて取得します
• 📊 検索アナリティクス - 柔軟なフィルタリングで検索パフォーマンスデータをクエリします
• 🗺️ サイトマップ情報 - サイトマップのステータスとインデックス登録統計を取得します
• 🔎 URL 検査 - 特定の URL の詳細なインデックス登録ステータスを確認します
• 📤 インデックス登録用 URL の送信 - URL のインデックス登録または削除を Google にリクエストします
• 📈 期間の比較 - 2 つの期間の検索パフォーマンスを比較します
• 🛡️ 堅牢なエラー処理 - 対処方法を含む詳細なエラーメッセージを表示します
• 🔄 自動再試行ロジック - レート制限や一時的な障害に対応します
• ✅ 入力検証 - API 呼び出しの前にすべてのパラメーターを検証します

前提条件

この MCP サーバーを使用するには、次のものが必要です。

1. Google Search Console

• Search Console に登録済みのサイト
• サイト所有権の確認済み
• クエリ対象の Search Console プロパティへのアクセス権

2. Google Cloud Platform（GCP）

• GCP プロジェクト（無料枠で十分です）
• Google Search Console API の有効化
• OAuth 2.0 クライアント ID 認証情報（デスクトップアプリタイプ）
• （任意）submit_url_for_indexing を使用する場合は Indexing API の有効化

💡 注：GCP のセットアップが必要なのは一度だけです。CLIENT_ID と CLIENT_SECRET は、Search Console 内の複数のサイトで再利用できます。

セットアップ

1. Claude Code の設定

プロジェクトのルートに .mcp.json を作成します。

{
  "mcpServers": {
    "google-search-console": {
      "command": "npx",
      "args": ["-y", "-p", "google-search-console-mcp-server", "google-search-console-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret",
        "GOOGLE_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

⚠️ 重要：args には次の 3 つすべてを含める必要があります。

1. "-y" - npx のプロンプトを自動承認します
2. "-p", "google-search-console-mcp-server" - パッケージ名
3. "google-search-console-mcp" - 実行ファイル名（パッケージ名とは異なります！）

💡 注：GOOGLE_REDIRECT_URI のデフォルト値は http://localhost:8080 です。別のポートを使用する場合を除き、指定する必要はありません。

2. Google OAuth 認証情報の取得

💡 ヒント：他のサービス（Supabase、Firebase など）で使用している既存の OAuth 2.0 クライアント ID を使うことも、新しく作成することもできます。

1. Google Cloud Console にアクセスします
2. プロジェクトを作成または選択します
3. API を有効にします：
   • 「APIs & Services」→「Enable APIs and Services」に移動します
   • **「Google Search Console API」**を検索して有効にします
   • submit_url_for_indexing を使用する場合は、（任意で）**「Indexing API」**を有効にします
4. OAuth 2.0 クライアント ID を作成または既存のものを使用します：
   • 「APIs & Services」→「Credentials」に移動します
   • 方法 A：既存の OAuth 2.0 クライアントを使用します（手順 5 に進みます）
   • 方法 B：「Create new」→「OAuth 2.0 Client ID」を選択し、アプリケーションの種類に 「Desktop app」 を選択します
5. 承認済みのリダイレクト URI を設定します：
   • OAuth 2.0 クライアント ID をクリックします
   • 「Authorized redirect URIs」の下にある「Add URI」をクリックします
   • http://localhost:8080 を追加します（末尾にスラッシュを付けないでください！）
   • 「Save」をクリックします
6. ⚠️ 重要：テストユーザーを追加します（OAuth 同意画面がテストモードの場合）：
   • 「OAuth consent screen」に移動します
   • 「Publishing status」を確認します。「Testing」と表示されている場合：
   • 「Test users」セクションまでスクロールします
   • 「+ ADD USERS」をクリックします
   • Google アカウントのメールアドレス（認証に使用するアカウント）を追加します
   • 「Save」をクリックします
   • この手順を行わないと、access_denied エラーが発生します！

💾 認証情報を保存してください：CLIENT_ID と CLIENT_SECRET をコピーします。次の手順で必要になります。

3. リフレッシュトークンを取得する

対話型セットアップコマンドを実行します。

npx -y -p google-search-console-mcp-server google-search-console-mcp-setup

次の項目の入力を求められます。

• GOOGLE_CLIENT_ID（手順 2 で取得したもの）
• GOOGLE_CLIENT_SECRET（手順 2 で取得したもの）
• GOOGLE_REDIRECT_URI（デフォルト値 http://localhost:8080 を使用する場合は Enter キーを押します）

認証用のブラウザーウィンドウが開きます。認証を許可すると、GOOGLE_REFRESH_TOKEN を含む 3 つすべての認証情報を含めた、完全な .mcp.json 設定がコマンドから出力されます。

設定をコピーして .mcp.json に貼り付け、Claude Code のウィンドウを再読み込みします。

使用方法

設定が完了すると、Claude Desktop または Claude Code でツールを使用できます。

Show me my Google Search Console sites

または

Get search performance data for example.com for the last 7 days

使用可能なツール

1. list_sites

アクセスできるすべての Search Console サイトを取得します。

パラメーター：なし

例：

Search Consoleのサイト一覧を教えて

2. get_analytics

指定した日付範囲の検索パフォーマンスデータを取得します。

パラメーター：

• siteUrl（必須）：サイト URL（例："https://example.com/"）
• startDate（必須）：開始日（YYYY-MM-DD）
• endDate（必須）：終了日（YYYY-MM-DD）
• dimensions（任意）：ディメンションの配列 ["query", "page", "country", "device", "searchAppearance"]
• rowLimit（任意）：最大行数（デフォルト：100、最大：25000）
• startRow（任意）：ページネーションの開始行

例：

example.comの過去7日間のトップクエリを取得して

example.comの2025年1月1日から1月31日までの、
ページ別とデバイス別のパフォーマンスを500件取得して

3. get_sitemaps

サイトのサイトマップ情報を取得します。

パラメーター：

• siteUrl（必須）：サイト URL

例：

example.comのサイトマップ情報を確認して

4. inspect_url

特定の URL のインデックス登録状況を確認します。

パラメーター：

• siteUrl（必須）：サイト URL（例："https://example.com/"）
• inspectionUrl（必須）：確認する完全な URL

例：

https://example.com/blog/article のインデックス状態を検査して

5. submit_url_for_indexing

Indexing API を使用して、Google に URL のインデックス登録をリクエストするか、URL の削除をリクエストします。

パラメーター：

• url（必須）：送信する完全な URL（例："https://example.com/page"）
• type（任意）：通知タイプ。"URL_UPDATED"（デフォルト）または "URL_DELETED"

例：

https://example.com/new-article をインデックスに送信して

https://example.com/old-page を削除申請して（type: URL_DELETED）

注：Google Cloud Console で Indexing API を有効にし、https://www.googleapis.com/auth/indexing スコープを設定する必要があります。

6. compare_periods

2 つの期間（例：今週と先週）の検索パフォーマンス指標を比較します。

パラメーター：

• siteUrl（必須）：サイト URL（例："https://example.com/"）
• currentStartDate（必須）：現在の期間の開始日（YYYY-MM-DD）
• currentEndDate（必須）：現在の期間の終了日（YYYY-MM-DD）
• previousStartDate（必須）：前の期間の開始日（YYYY-MM-DD）
• previousEndDate（必須）：前の期間の終了日（YYYY-MM-DD）
• dimensions（任意）：グループ化に使用するディメンションの配列
• rowLimit（任意）：最大行数（デフォルト：100、最大：25000）

例：

Compare this week vs last week performance for example.com

Compare query performance for example.com between January 2025 and December 2024
(currentStartDate: 2025-01-01, currentEndDate: 2025-01-31,
 previousStartDate: 2024-12-01, previousEndDate: 2024-12-31,
 dimensions: ["query"])

API の制限

• 1 日あたりの割り当て：プロジェクトあたり 2,000 リクエスト
• 100 秒あたり：600 リクエスト
• データの利用可能期間：過去 16 か月まで
• データの遅延：通常 2〜3 日

エラー処理と再試行ロジック

この MCP サーバーには、包括的なエラー処理機能が含まれています。

自動再試行

• レート制限（429）：指数バックオフを使用して自動的に再試行します
• サーバーエラー（5xx）：待機時間を延ばしながら最大 3 回再試行します
• 一時的な失敗：群集アクセスを防ぐため、ジッターを含むスマートな再試行ロジックを使用します

入力の検証

すべてのツールは、API を呼び出す前に入力を検証します。

• サイト URL：URL の形式と構造を検証します
• 日付：YYYY-MM-DD 形式と日付範囲の妥当性を検証します
• 行数制限：制限が API の制約（1〜25,000）の範囲内であることを確認します

詳細なエラーメッセージ

エラーメッセージには次の内容が含まれます。

• 問題の内容を明確に説明する記述
• HTTP ステータスコード
• 問題を解決するための具体的な手順

例：

Access denied for list sites (403)
Verify your authentication credentials and ensure you have access to this Search Console property.
You may need to add your account as a test user in Google Cloud Console.

トラブルシューティング

セットアップの問題

認証中の「invalid_client」エラー

問題：セットアップコマンドの実行時に、Error during authentication: invalid_client が表示されます。

原因と解決策：

1. CLIENT_ID と CLIENT_SECRET が一致していない

   • GCP Console の同じ OAuth 2.0 クライアントから取得したものか確認します
   • Google Cloud Console から直接コピーし直します

2. Authorized redirect URIs に http://localhost:8080 がない

   • 他のサービス（Supabase、Firebase など）の OAuth 認証情報を再利用している場合
   • 解決策：OAuth 2.0 クライアントの設定で「Authorized redirect URIs」に http://localhost:8080 を追加します
   • 複数のリダイレクト URI を設定できます（例：https://xxx.supabase.co/auth/v1/callback と http://localhost:8080）

3. CLIENT_SECRET が再生成された

   • GCP Console でシークレットをリセットした場合は、新しいものを使用します
   • 古いシークレットは直ちに無効になります

「could not determine executable to run」エラー

問題：npx google-search-console-mcp-server を実行すると、「could not determine executable to run」で失敗します。

解決策：パッケージ名と実行可能ファイル名は異なります。正しい .mcp.json 設定を使用してください。

{
  "mcpServers": {
    "google-search-console": {
      "command": "npx",
      "args": ["-y", "-p", "google-search-console-mcp-server", "google-search-console-mcp"],
      "env": { ... }
    }
  }
}

Claude Code で MCP サーバーに「✘ failed」と表示される

デバッグ手順：

1. エラーの詳細を確認する：

   • Claude Code の MCP ステータス画面で、失敗したサーバー上で Enter キーを押します
   • 下にスクロールして stderr（エラー出力）を確認します

2. 手動でテストする：

   cd your-project-directory
   export GOOGLE_CLIENT_ID="your-id"
   export GOOGLE_CLIENT_SECRET="your-secret"
   export GOOGLE_REFRESH_TOKEN="your-token"
   npx -y google-search-console-mcp-server
   

3. よくある原因：

   • Search Console API が有効になっていない：GCP Console で有効にします
   • 認証情報が間違っている：CLIENT_ID、CLIENT_SECRET、REFRESH_TOKEN を確認します
   • トークンの有効期限切れ：セットアップコマンドを再実行して、新しい REFRESH_TOKEN を取得します
   • npx キャッシュの問題：npx のキャッシュをクリアします：rm -rf ~/.npm/_npx

4. Claude Code を再読み込みする：.mcp.json を修正した後、ウィンドウを再読み込みします（Ctrl/Cmd + Shift + P → 「Developer: Reload Window」）

実行時エラー

「Missing required environment variables」

.mcp.json ファイルに、GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET、GOOGLE_REFRESH_TOKEN の3つの環境変数がすべて設定されていることを確認してください。

「redirect_uri_mismatch」

Google Cloud Console の OAuth 2.0 クライアント設定にある Authorized redirect URIs に、http://localhost:8080（末尾のスラッシュなし）が追加されていることを確認してください。

「Error 403: access_denied」

1. ⚠️ 最もよくある原因 — OAuth 同意画面がテストモードになっている：
   • GCP Console で「OAuth consent screen」に移動します
   • 「Publishing status」が 「Testing」 の場合は、必ず自分のメールアドレスを「Test users」に追加します
   • 「Test users」セクションの「+ ADD USERS」をクリックします
   • Google アカウントのメールアドレス（認証に使用するもの）を追加します
   • 「Save」をクリックします
   • access_denied エラーの原因として最も多いのはこれです！
2. API が有効になっていない：GCP Console で「Google Search Console API」を有効にします
3. サイトへのアクセス権がない：クエリ対象の Search Console プロパティにアクセスできることを確認します

「Invalid site URL format」

サイト URL は、次のような完全な URL である必要があります。

• https://example.com/（URL プレフィックス プロパティの場合）
• sc-domain:example.com（ドメイン プロパティの場合）

「Date range too old」

Search Console のデータを利用できるのは、直近16か月分のみです。

「Rate limit exceeded」

ツールはバックオフしながら自動的に再試行します。それでも制限に達する場合は、次のことを試してください。

• リクエストの間隔を数分空ける
• アナリティクスのクエリで rowLimit を小さくする
• API の制限：1日あたり2,000リクエスト、100秒あたり600リクエスト

トークンの有効期限切れ

認証エラーが表示される場合、リフレッシュトークンの有効期限が切れている可能性があります。認証セットアップを再実行してください。

npx -y -p google-search-console-mcp-server google-search-console-mcp-setup

新しい GOOGLE_REFRESH_TOKEN を .mcp.json にコピーします。

開発

ビルド

npm run build

ウォッチモード

npm run dev

再認証

node build/auth/setup-auth.js

プロジェクト構成

src/
├── index.ts                 # MCP server entry point
├── auth/
│   ├── google-auth.ts       # OAuth 2.0 client
│   └── setup-auth.ts        # Authentication CLI
├── tools/
│   ├── list-sites.ts        # List sites tool
│   ├── get-analytics.ts     # Search analytics tool
│   ├── get-sitemaps.ts      # Sitemap info tool
│   ├── inspect-url.ts       # URL inspection tool
│   ├── submit-url.ts        # Submit URL for indexing
│   └── compare-periods.ts   # Compare time periods
├── types/
│   └── index.ts             # Type definitions
└── utils/
    └── error-handler.ts     # Error handling & validation

セキュリティに関する注意事項

• .env ファイルや .mcp.json ファイルをバージョン管理にコミットしないでください
• リフレッシュトークンを安全に保管してください
• 可能な場合は読み取り専用スコープ（webmasters.readonly）を使用してください
• リフレッシュトークンを使用するとアクセスを継続できます。安全に保管してください

ライセンス

MIT

コントリビューション

コントリビューションを歓迎します！お気軽にイシューやプルリクエストを送信してください。

---

リソース

• Google Search Console API のドキュメント
• Model Context Protocol
• Claude Code のドキュメント