Google Search Console

Google Search Console MCP

English · イタリア語

Google Search Console API を利用する 17 個の読み取り専用ツールと、代理店が自社名を入れて英語またはイタリア語でクライアントに送付できる、決定論的なホワイトラベル HTML 監査レポートを提供します。

認証情報なしで、コミット済みの合成データからレポートを再生成できます：

python scripts/render_sample_report.py --lang en --open

インストール

Claude Code

/plugin marketplace add acamolese/google-search-console-mcp
/plugin install google-search-console@acamolese

このプラグインには、MCP サーバー、5 つのスキル（週次レビュー、カニバリゼーションチェック、インデックス監査、コンテンツの機会、ホワイトラベルのクライアント監査）、および 3 つの認証情報を設定するためのプロンプトが含まれています。

Claude Desktop

最新リリースから google-search-console.mcpb をダウンロードして開きます。uv をインストールしておく必要があります。または、設定ファイルを直接編集します：

{
  "mcpServers": {
    "google-search-console": {
      "command": "uvx",
      "args": ["mcp-google-search-console"],
      "env": {
        "GSC_CLIENT_ID": "...",
        "GSC_CLIENT_SECRET": "...",
        "GSC_REFRESH_TOKEN": "..."
      }
    }
  }
}

Cursor、Codex、Gemini CLI、Zed

どの MCP クライアントでも、同じ 3 行で設定できます。コマンドは uvx、引数は mcp-google-search-console、環境変数は 3 つの GSC_* です。

# Codex
codex mcp add google-search-console -- uvx mcp-google-search-console

# Gemini CLI
gemini mcp add google-search-console uvx mcp-google-search-console

Docker

docker build -t mcp-gsc .
docker run --rm -p 127.0.0.1:8765:8765 \
  -e GSC_CLIENT_ID -e GSC_CLIENT_SECRET -e GSC_REFRESH_TOKEN \
  -v "$PWD/reports:/reports" mcp-gsc

コンテナは /mcp でストリーミング可能な HTTP 通信を行います。独自の認証機能はありません。ループバック上、またはリバースプロキシの背後で使用してください。

認証

OAuth スコープは webmasters.readonly のみです。このサーバーのどのツールも、Search Console のプロパティやサイトマップなどを変更できません。

認証情報は、次の順序で解決されます：

1. 設定されている場合は GSC_AUTH_MODE（oauth、service_account、adc）
2. GSC_SERVICE_ACCOUNT_FILE または GSC_SERVICE_ACCOUNT_JSON
3. GSC_CLIENT_ID + GSC_CLIENT_SECRET + GSC_REFRESH_TOKEN
4. ~/.config/mcp-google-search-console/ 内のトークンファイル
5. Application Default Credentials

OAuth の初回設定

1. Google Cloud Console で Google Search Console API を有効にし、種類が デスクトップアプリ の OAuth クライアントを作成します。

2. クライアントをエクスポートするか、ダウンロードした JSON を ~/.config/mcp-google-search-console/oauth_credentials.json として保存します：

   export GSC_CLIENT_ID="...apps.googleusercontent.com"
   export GSC_CLIENT_SECRET="..."
   uvx mcp-google-search-console auth
   

3. ブラウザー認証フローでは、ステートレスな設定用に 3 行の export コマンドが表示されます。また、0600 の権限で ~/.config/mcp-google-search-console/token.json にトークンも保存されます。

ヘッドレスマシンでは、ノート PC で auth を実行し、3 つの環境変数をコピーしてください。--no-browser を指定すると URL が表示され、ブラウザーは開きませんが、ローカルのリダイレクトは引き続き必要です。

サービスアカウント

Search Console のプロパティに対する読み取りアクセス権をサービスアカウントのメールアドレスに付与し、サーバーが鍵を参照するように設定します：

export GSC_SERVICE_ACCOUNT_FILE=/path/to/key.json
# or, for a container:
export GSC_SERVICE_ACCOUNT_JSON='{"type":"service_account",...}'

動作確認

uvx mcp-google-search-console doctor

使用中の認証モード、トークンの有効期限、アカウントが読み取り可能なプロパティの数、および各ツールが適用するデフォルト設定が表示されます。シークレットはマスクされます。認証情報を解決できない場合は終了コード 1 で終了します。これは「サーバーが起動しない」という報告の多くに対する答えです。

ツール

ツール	回答する内容
gsc_sites	このアカウントが読み取れるプロパティと、その正確な形式
gsc_site_details	1 つのプロパティの権限レベルと種類
gsc_query	フィルター、ディメンション、ページネーションを指定した検索アナリティクスレポート
gsc_performance_overview	前の期間と比較したサイトの上昇または下降
gsc_compare_periods	クリック数の差が大きい順に並べた、2 つの期間の変化
gsc_quick_wins	少し後押しすれば成果が見込める、上位に近いクエリ
gsc_ctr_gaps	ランクインしているものの、クリックされていないページ
gsc_cannibalization	複数のページが競合しているクエリ
gsc_traffic_drops	クリック数が減少したページと、それぞれの考えられる原因
gsc_content_decay	月ごとに順位が下がっているページ
gsc_alerts	今日知らせる価値があるほど大きく変動した項目
gsc_portfolio	すべてのプロパティの概要。悪い順に表示
gsc_indexing_issues	これらの URL がインデックス登録されているかどうか、および未登録の場合はその理由
gsc_inspect_url	1 つのページの完全な URL 検査
gsc_sitemaps	Google が把握しているサイトマップと、エラーおよび警告
gsc_doctor	設定内容と、API が応答するかどうか
gsc_audit	完全な HTML レポート

繰り返し使うワークフローを、3 つのプロンプトで実行できます。gsc_weekly_report、 gsc_indexing_audit、gsc_content_opportunities。

このサーバーを選ぶ理由

	こちら	一般的な GSC MCP サーバー
クライアント向けレポート	自己完結型の HTML。英語またはイタリア語に対応し、ホワイトラベル化が可能	なし
分析	カニバリゼーション、CTR のギャップ、減衰、減少の診断をサーバー側で実行	生の行データをモデルが分析
しきい値	プロパティの規模に合わせて調整	固定、またはなし
日付	period="last_month"、days=28 をサーバー側で解決	明示的な日付のみ
データの鮮度	デフォルトで dataState=all。UI と一致	final のみ
認証	OAuth、サービスアカウント、ADC	OAuth のみ
出力	デフォルトは TSV。整形済み JSON のおよそ 3 分の 1 のトークン数	json.dumps(indent=2)
エラー	Google の理由と、対処方法	HTTP ステータスのみ
テスト	280 件以上。mcp の 2 つのメジャーバージョン、3 つの OS で実施	通常はなし

レポートのカスタマイズ

色、ロゴ、レポート名、ブランド用語、しきい値は JSON ファイルで指定します。 branding_path を渡すか、次の場所に配置すると、すべてのレポートに適用されます。 ~/.config/mcp-google-search-console/branding.json：

{
  "brand_name": "Your Agency",
  "logo": "logo.png",
  "brand_terms": ["clientbrand", "client brand"],
  "colors": { "primary": "#2b6cb0", "primary_dark": "#1a365d" },
  "thresholds": { "min_impressions": 200 }
}

ローカルのロゴはドキュメントに Base64 エンコードされます。リモートのロゴは allow_external_fonts が true の場合にのみ保持されます。そうでない場合、レポートには 外部 URL が一切含まれないことが保証されるためです。CDN もフォントサービスもなく、 クライアントが開いたときに外部へ通信するものはありません。

brand_terms は見た目以上に重要です。指定しない場合、ドメインの最初のラベルが ブランドとして使われます。略称、持株会社、独自に作った名称の場合はこれが正しくなく、 ブランドと非ブランドの分類が誤って表示されても気づけません。推測が必要だった場合は、 レポートにその旨が表示されます。

クォータと制限

• 16 か月分の日次データを利用できます。それより古いデータは、どのような料金を払っても利用できません。
• 時間単位のデータ：過去 10 日分のみです。
• URL 検査：1 分あたり 600 件、プロパティごとに 1 日あたり 2,000 件です。大規模なサイトでは、この制限が問題になります。
• 検索アナリティクス：サイトごとに 1 分あたり 1,200 クエリです。レスポンスはメモリに 6 時間（検査の場合は 1 時間）キャッシュされます。no_cache=true を指定するとキャッシュを迂回します。
• 行数：API 呼び出しあたり 25,000 行です。ツールのデフォルトは 100 行で、上限は 1,000 行です。ページネーションには start_row を使います。上限に達した場合はレスポンスに報告され、通知なしに適用されることはありません。

環境変数

変数	デフォルト	用途
GSC_CLIENT_ID, GSC_CLIENT_SECRET, GSC_REFRESH_TOKEN		ステートレス OAuth
GSC_SERVICE_ACCOUNT_FILE, GSC_SERVICE_ACCOUNT_JSON		サービスアカウント
GSC_AUTH_MODE	auto	oauth、service_account、adc を強制
GSC_REPORT_LANGUAGE	en	レポートの言語：en または it
GSC_DATA_STATE	all	all は今日の部分データを含み、final は含みません
GSC_CACHE_TTL_SECONDS	21600	レスポンスキャッシュの TTL。0 で無効になります
GSC_INSPECT_CONCURRENCY	5	URL 検査の並列数
GSC_LOG_LEVEL	WARNING	ログ出力。常に stderr に出力
MCP_TRANSPORT, MCP_HOST, MCP_PORT	stdio	トランスポート

トラブルシューティング

spawn uvx ENOENT — クライアントが PATH 上で uvx を見つけられません。GUI アプリはシェルの PATH を引き継ぎません。絶対パスを使用してください。通常、which uvx でパスを確認でき、/Users/you/.local/bin/uvx のようになります。

すべての呼び出しで 403 forbidden が発生する — ほとんどの場合、プロパティの形式が原因です。ドメインプロパティは sc-domain:example.com、URL プレフィックスプロパティは末尾のスラッシュを含む https://example.com/ です。gsc_sites は正確な文字列を返します。

401 invalid_grant — 更新トークンが取り消されたか、期限切れです。「テスト」中の OAuth アプリの更新トークンは Google によって 7 日後に期限切れになります。アプリを公開するか、auth を再実行してください。

403 quotaExceeded — 1 日あたりの URL 検査の割り当てを使い切りました。明日リセットされます。それ以上の再試行は行われません。

小規模なサイトでレポートが空になる — レスポンスのメタデータにあるしきい値を確認してください。プロパティに応じて調整されますが、下限（表示回数 50、クリック数 10）は適用されます。しきい値を下げるには thresholds を渡してください。

その他の場合 — doctor を実行し、その出力を issue に添付してください。

セキュリティ

• 読み取り専用スコープを要求し、範囲を拡大することはありません。
• トークンファイルは 0600 権限でアトミックに書き込まれます。環境経由で提供された認証情報がディスクに書き込まれることはありません。
• gsc_doctor はクライアント ID をマスクし、トークンを返しません。
• テレメトリや分析はなく、Google の API 以外のホストへのリクエストもありません。

報告ポリシーについては、SECURITY.md を参照してください。

開発

uv venv && uv pip install -e ".[dev]"
ruff check src tests scripts && ruff format --check src tests scripts
pytest -q --cov=google_search_console_mcp
python scripts/sync_versions.py
python scripts/render_sample_report.py --lang it --open

テストでネットワークに接続することはありません。ライブテストは -m live の背後にあり、GSC_LIVE_TESTS=1 と認証情報が必要です。CI で実行されることはありません。

リリースについては、docs/RELEASING.md を参照してください。コードで扱われていない判断は、docs/DECISIONS.md に記録されています。

ライセンス

MIT。Chart.js 4.5.1 は src/google_search_console_mcp/static/ にベンダー同梱されており、こちらも MIT ライセンスです。ライセンス文書も同じ場所にあります。