Google Search Console MCP

Google Search Console API 用の MCP サーバー — 検索パフォーマンスデータ、URL のインデックスステータス、サイトマップ管理、プロパティ一覧を提供します。

1 つのコードベースから 3 つの方法で動作します: stdio(ローカル、npx 経由)、Streamable HTTP(セルフホスト)、Cloudflare Workers(URL でホスト)。MCP 2026-07-28 を実装し、2025-11-25、2025-06-18、2025-03-26 への自動フォールバックも備えているため、プロトコル変更のどちらの側のクライアントでも動作します。

ランタイム依存関係はゼロです。

クイックスタート

npx google-search-console-mcp auth

Google OAuth クライアントの作成、同意フローの実行、ライブ API に対する認証情報の検証、そして MCP クライアント用にそのまま貼り付けられる設定ブロックの出力までを案内します。所要時間は 3 分で、ほとんどは Google Cloud の UI を待つ時間です。

その後、出力された JSON をクライアント設定に貼り付けて、クライアントを再起動します。

Related MCP server: searchconsole-mcp

ツール

Search Console API v1 のすべてのメソッドに加え、2 つの複合ツールを提供します。

サイトの検証と sites.add/sites.delete は意図的に公開していません — プロパティの追加と検証はブラウザでの操作であり、エージェントツールに含めるべきものではないためです。

サーバーは プロンプト(performance_review、indexing_audit、query_opportunities、sitemap_health)と リソース(gsc://guide/search-analytics、gsc://guide/url-inspection、gsc://guide/sitemaps)も提供しており、エージェントは必要に応じて読み取ることができます。

認証

ステップ 1 — Google OAuth クライアントを作成する

これは一度だけ行う作業です。サーバーが代わりに行うことはできません。Google ではコンソールでの人間の操作が必要です。

1. Google Cloud Console を開き、プロジェクトを選択または作成します。

2. そのプロジェクトで Search Console API を有効にします。

3. OAuth 同意画面を設定します。個人利用であれば 外部 で問題ありません。テストユーザー に自分の Google アカウントを追加します。

4. 認証情報 → 認証情報を作成 → OAuth クライアント ID に進みます。アプリケーションの種類は デスクトップアプリ を選択します。

5. クライアント ID と クライアントシークレット をコピーします。

テスト中 vs 公開済み。 同意画面が テスト中 の間、Google はリフレッシュトークンを 7 日間 で失効させ、毎週 auth を再実行する必要があります。アプリを公開(同意画面 → アプリを公開)すると、トークンは永続化されます。単一ユーザーの内部ツールの場合、webmasters スコープに限定していれば、公開は安全であり、Google の審査は不要です。

ステップ 2 — セットアップフローを実行する

npx google-search-console-mcp auth

127.0.0.1 で提供される小さなセットアップページが開きます。クライアント ID とシークレットを貼り付け、フルアクセスか読み取り専用かを選択すると、同意フローを実行し、コードを(PKCE を使用して)リフレッシュトークンと交換し、list_sites を呼び出して認証情報が機能することを確認します — アクセスできる正確なプロパティが表示されます。

最後のページでは、認証情報ブロブと、Claude Desktop、Claude Code、リモートデプロイ用の貼り付け可能な設定が表示され、それぞれにコピーボタンが付いています。同じ値はフォールバックとしてターミナルにも出力されます。

ヘッドレスマシンや SSH 経由の場合は、代わりに auth --terminal でプロンプト駆動のバージョンを使用します。

返されるのは 認証情報ブロブ — クライアント ID、クライアントシークレット、リフレッシュトークンを含む base64url エンコードされた JSON です:

eyJ2IjoxLCJjcmVkZW50aWFscyI6eyJ0eXBlIjoib2F1dGhfcmVmcmVzaF90b2tlbiIsImNsaWVu…

ブロブはパスワードとして扱ってください。 それを保持する人は誰でも、myaccount.google.com/permissions で失効させるまで、あなたの Search Console にアクセスできます。

これは単一の不透明な文字列として存在するため、1 つの値でサーバーが必要とするすべてを運べます — ディスク上の認証情報ファイルなしで、環境変数や Authorization ヘッダーにそのまま入ります。

OAuth フローに代わる方法

サービスアカウント。 CI やチーム所有のプロパティに便利です。Google Cloud で作成し、Search Console のプロパティ(設定 → ユーザーと権限)でその client_email をユーザーとして追加します。ダウンロードしたキーファイルを直接エンコードします:

base64 -i service-account.json | tr -d '\n'

サーバーは生のサービスアカウントキーをブロブとして受け入れます — エンベロープは不要です。

既存のアクセストークン。 {"type":"access_token","access_token":"ya29..."} を設定します。リフレッシュはできないため、短命のスクリプトにのみ適しています。

スコープ

auth 中に読み取り専用を選択すると、より狭いスコープが要求されます。サーバー側の --read-only は、API に到達する前に変更系ツールを拒否する、別の二重防御ブロックです。

実行方法

ローカル (stdio)

auth が出力する設定:

{
  "mcpServers": {
    "google-search-console": {
      "command": "npx",
      "args": ["-y", "google-search-console-mcp"],
      "env": { "GSC_CREDENTIALS": "<your blob>" }
    }
  }
}

設定ファイルの場所:

毎回 npx を経由したくない場合は、正しくインストールします:

npm install -g google-search-console-mcp

セルフホスト HTTP

GSC_CREDENTIALS=<blob> npx google-search-console-mcp http --port 8787

POST http://127.0.0.1:8787/mcp を提供します。デフォルトではループバックにバインドされます — 公開する場合は意図的に --host 0.0.0.0 を渡し、その場合は TLS を前面に置いてください。

ブラウザベースのクライアントは、名前を指定しない限り拒否されます。これは、サーバーが自身の認証情報を保持している場合、訪問した任意のページから操作される可能性があるためです。通常の MCP クライアントは Origin を送信しないため影響を受けません。ブラウザのクライアントは、そのオリジンをリストに追加する必要があります:

npx google-search-console-mcp http --allowed-origins http://localhost:6274   # MCP Inspector

拒否されたオリジンは、ブラウザが読み取れない 403(拒否時に CORS ヘッダーを付けない設計)を返すため、一般的な CORS エラーとして表示されます。ブラウザクライアントが接続できない場合は、サーバーの Origins: 起動行を確認してください。--allowed-origins '*' でチェックを無効にします。

Cloudflare Workers

git clone https://github.com/russjeffery/google-search-console-mcp.git
cd google-search-console-mcp
npm install
npx wrangler deploy

エンドポイントは https://google-search-console-mcp.<subdomain>.workers.dev/mcp です。

デフォルトでは Worker はシークレットを保存しません。 各クライアントが自身の認証情報ブロブをベアラートークンとして送信するため、共有デプロイは誰の Google 認証情報も保持せず、同じ URL の異なるユーザーは自分のプロパティのみを表示できます。

代わりにプライベートな単一テナントデプロイの場合:

npx wrangler secret put GSC_CREDENTIALS     # your blob
npx wrangler secret put MCP_SHARED_SECRET   # token clients must present

クライアントはブロブではなく共有シークレットを送信します。

wrangler.jsonc のオプションの vars:

リモートサーバーへのクライアント接続

{
  "mcpServers": {
    "google-search-console": {
      "type": "http",
      "url": "https://your-worker.workers.dev/mcp",
      "headers": { "Authorization": "Bearer <your blob>" }
    }
  }
}

Claude Web またはデスクトップ UI で、設定 → コネクタ → カスタムコネクタを追加 から追加します。

自分のデプロイ用にこれを入力して出力します:

npx google-search-console-mcp config --url https://your-worker.workers.dev/mcp

CLI

google-search-console-mcp [command] [options]

  stdio     Run as a stdio MCP server (default)
  http      Run a local Streamable HTTP MCP server
  auth      Guided setup in your browser: OAuth flow, blob, client config
  config    Print client config for existing credentials
  doctor    Verify credentials by calling the API

doctor は何かが機能しないときに最初に試すべきものです — 「認証情報が間違っている」と「クライアントがサーバーを起動できない」を区別します。

オプション: --credentials <blob>、--site <siteUrl>、--read-only、--port、--host、--endpoint、--secret、--allowed-origins、--url、--terminal、--no-browser。

--allowed-origins はカンマ区切りリストを受け取ります。未設定の場合は非ブラウザクライアントのみです。エントリは大文字小文字を区別せずに照合され、末尾のスラッシュは無視されます。

--site はデフォルトのプロパティを設定するため、ツールは siteUrl を省略できます — デプロイが常に 1 つのサイトのみを対象とする場合に便利です。

プロトコルサポート

2026-07-28 改訂版は Streamable HTTP を大幅に変更しました: initialize ハンドシェイクなし、セッションなし、Mcp-Session-Id なし、GET ストリームなし、params._meta 内のリクエストごとのメタデータが HTTP ヘッダーにミラーリングされます。公式 TypeScript SDK はまだこれを実装していないため、ここでのプロトコル層は手書きで、2 つの時代に対応しています。

時代はリクエストごとに検出されます: 最新の _meta を持つリクエストは最新として処理され、initialize はレガシーを選択します。エンドポイントへの GET と DELETE は、改訂版の規定どおり 405 を返します。

ヘッダー検証はデフォルトで厳格です(仕様に準拠)。クライアントがヘッダーをミラーリングせずに最新の _meta を送信する場合は、ダウングレードするのではなく MCP_STRICT_HEADERS=0(または --loose-headers)を設定してください。

認可について: 仕様のOAuth 2.1フローは、サーバーが独自の認可サーバーを持つリソースサーバーであることを前提としています。このサーバーは代わりにベアラートークンを使用してGoogle認証情報を直接運びます — 仕様ではカスタム戦略が許可されており、ホスト型デプロイメントが秘密情報を保持せず、ユーザーデータベースも不要であることを意味します。トレードオフとして、自動OAuth検出を期待するクライアントは、上記のようにヘッダーを手動で設定する必要があります。

データの扱い方

Search Consoleデータの4つの特性が、ほとんどの誤った結論を引き起こします。ツールの説明と同梱のスキルがこれらを詳しくカバーしています。簡単に言うと:

1. データには約3日の遅延があります。 lastDaysを使用すると、ツールが安全なウィンドウを選択します。今日で終わる範囲は偽の減少を示します。

2. クエリデータはプライバシーフィルタリングされます。 queryでグループ化すると、まれなクエリが静かに除外されるため、クエリレベルのクリック数はプロパティ合計に合計されません。そのギャップは失われたトラフィックではありません。

3. 順位は逆転しています。 順位3は順位8より優れており、負の変化は改善です。compare_search_analyticsは明示的なimprovedフラグを返します。

4. 平均値は相殺されます。 見出しのフラットな数字は、大きな相殺的な動きを日常的に隠します。何も変わっていないと結論する前に、ページまたはクエリでグループ化してください。

クォータ

• 検索アナリティクス: プロパティあたり約1,200クエリ/分。

• URL検査: プロパティあたり約2,000/日 — これが制約要因です。意図的にサンプリングしてください。

APIでは利用不可

集計インデックスカバレッジレポート、ライブURLテスト、インデックス登録のリクエスト、Core Web Vitals、手動による対策、セキュリティ問題、リンクレポート、削除にはAPI相当機能がないため、ここには含まれていません。URLごとのinspect_urlがカバレッジに関する質問に対する最も近い代替手段です。

エージェントスキル

skills/google-search-console/は、エージェントにこれらのツールをうまく使う方法を教える、すぐにインストールできるスキルです — 上記の落とし穴、トラフィック変化の診断ラダー、機会発見のヒューリスティック、カバレッジ状態のルックアップテーブルが含まれています。

cp -r skills/google-search-console ~/.claude/skills/

同じ参考資料は、サーバーのgsc://guide/*リソースを通じて実行時に利用できるため、スキルがインストールされていないエージェントでも読むことができます。

開発

npm install
npm run build       # compile to dist/
npm run typecheck
npm test
npm run cf:dev      # Worker locally via wrangler

HTTPトランスポートに対する簡単な手動チェック:

GSC_CREDENTIALS=<blob> npm run build && node dist/bin/cli.js http &

curl -s http://127.0.0.1:8787/mcp \
  -H 'content-type: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/list' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}' | jq '.result.tools[].name'

トラブルシューティング

セキュリティ

• 認証情報ブロブはあなたのGoogleアクセスです。コミットせず、共有ドキュメントに貼り付けないでください。myaccount.google.com/permissionsで失効させてください。

• HTTPモードはデフォルトで127.0.0.1にバインドし、DNSリバインディングをブロックするためにALLOWED_ORIGINSに対してOriginを検証します。未設定の場合はブラウザオリジンが許可されません — 明示的にリストするか、*を使用してチェックをオプトアウトしてください。/healthと/は例外で、認証情報を公開する機能は公開しません。

• 共有シークレットの比較は長さチェックされ、定数時間で実行されます。

• デフォルトのWorkerデプロイメントは認証情報を一切保存しません。

• --read-only / GSC_READ_ONLY=1は、付与されたOAuthスコープとは独立してサイトマップの変更をブロックします。

ライセンス

MIT