Google Search Console

google-search-console-mcp

Google Search Console向けのModel Context Protocol（MCP）サーバーです。Google から見たサイトの状況を確認できるサービスを読み取り、設定します。

Claude Code、Claude Desktop、Codex などの MCP クライアントを使って、プロパティを作成して所有権を証明したり、サイトマップを送信・更新したり、任意の URL のインデックス登録状況を確認したり、パフォーマンスレポート全体を照会したりできます。取り消せない操作は事前に人の確認を求め、書き込みツールは完全に無効化できます。

21 個のツールは上限であって、最小数ではありません。GSC_ALLOW_TOOLS=essential を設定すると、厳選された 5 個だけが登録されます。モデルは 21 個より 5 個からのほうが、はるかに確実に適切なツールを選択できます。詳しくは読み込むツールの選択をご覧ください。

異なる点

実際に利用できるプロパティを作成できます。 プロパティを作成するには、固定された順序で4つの手順を踏む必要があります。確認トークンを取得し、DNSまたはページに配置し、所有権を確認してから、プロパティを追加します。しかし、Google の API はこの順序を強制しません。最初に sites.add を呼び出すと_成功_し、あらゆる一覧に表示される一方で、すべてのデータに対して 403 を返すプロパティが作成されます。これは権限の不具合のように見えますが、そうではありません。setup_site は不足している手順を報告し、貼り付ける正確な DNS レコードを提示します。sites.add だけを公開するサーバーで追加できるのは、すでに手動で所有権が確認されたプロパティだけです。

API は1つではなく、3つあります。 Search Console v1 には10個のメソッドがありますが、所有権に関する機能は含まれていません。Site Verification は独立したサービスで、独自のスコープとホストを持ち、同じサイトの名前の付け方も互換性がありません。そこでの sc-domain:example.com は {type: INET_DOMAIN, identifier: example.com} であり、プロパティの表記をそのまま渡すと受け付けられ、sc-domain:example.com という名前のドメインとして検証されます。Indexing API は3つ目の API です。この3つすべてに対応しており、それらの間の変換は src/site-identity.ts にあります。

数値が正確です。 検索アナリティクスは、合計値を含む表として返されます。CTR は行ごとの平均ではなく合計値から計算され、平均掲載順位はインプレッション数で加重されます。加重しない場合、80位にランクインしている検索クエリが多数あると、実際には平均12位のプロパティでも平均順位が90位台まで押し上げられます。また、クエリのディメンションを使うと行の合計がプロパティの合計と一致しないことも、結果に明記されます。Google は匿名性を保つため、頻度の低いクエリを除外しており、一般に全インプレッション数の3分の1以上が対象です。この注意書きなしに表示される合計値は、人々にそのまま引用されてしまう数値です。

これらの API の注意点を把握しています。 https://example.com/ の末尾のスラッシュは必須で、省略すると 403 が返されます。同じサイトのドメインプロパティと URL プレフィックスプロパティは、データが異なる別々のプロパティです。そのため、ホスト名だけが指定された場合は推測せずに拒否します。日付は太平洋時間で数えられるため、UTC で計算した last7days は、Google にデータがない日を指定してしまいます。hour ディメンションは dataState: HOURLY_ALL がないと、何も返さずに処理を終えます。Google は空の配列を完全に省略するため、新しい認証情報で取得したプロパティ一覧は {} になります。また、Indexing API は所有する任意の URL に対して 200 を返しますが、処理するのは JobPosting と BroadcastEvent のページだけです。

要件

• Node.js 22 以降（またはコンテナーイメージ）
• Google の認証情報 — サービスアカウントキー、OAuth2 リフレッシュトークン、またはアプリケーションのデフォルト認証情報
• 使用する API を Google Cloud プロジェクトで有効化すること：Search Console API、および個別に Site Verification API と Indexing API

設定

認証情報がなくてもサーバーは起動し、ツールを一覧表示します。その後、呼び出しはすべて Google のエラーではなく、セットアップ手順を返して失敗します。これは意図的な動作であり、レジストリやサンドボックスのインスペクターがサーバーを調べられるようにするためです。

変数	説明
GSC_SERVICE_ACCOUNT_KEY	サービスアカウントキー。生の JSON または Base64 エンコードされた JSON を指定します
GSC_SERVICE_ACCOUNT_KEY_FILE	サービスアカウントキーファイルのパス。上記の代替手段です。両方を設定するとエラーになります
GSC_CLIENT_ID	OAuth2 クライアント ID
GSC_CLIENT_SECRET	OAuth2 クライアントシークレット
GSC_REFRESH_TOKEN	OAuth2 リフレッシュトークン。OAuth2 の 3 つの変数はすべてセットで必要です
GOOGLE_APPLICATION_CREDENTIALS	アプリケーションのデフォルト認証情報。GSC_ 認証情報が設定されていない場合に使用します
GSC_SITE_URL	デフォルトのプロパティ。例：sc-domain:example.com または https://example.com/。これを設定すると、すべての場所で site_url が任意になります
GSC_ALLOWED_SITES	このサーバーが操作できるプロパティをカンマ区切りで指定します。それ以外はすべて拒否されます
GSC_READ_ONLY	true（または 1／yes）を指定すると、読み取り専用の 12 個のツールのみを登録します
GSC_ALLOW_TOOLS	カンマ区切りのツール名、list_* プレフィックス、または essential を指定します
GSC_DENY_TOOLS	同じ形式で指定し、許可リストに残った項目から差し引きます
ELICITATION	false を指定すると、承認ダイアログが 2 回呼び出しのトークンに置き換わります。プレフィックスは付きません

認証情報はこの順序で試され、明示的に指定したものが環境にあるものより優先されます。OAuth の 3 つの値が一部だけ設定されている場合、アプリケーションのデフォルト認証情報へのフォールバックは行われず、起動エラーになります。フォールバックすると、マシンにログインしているアカウントでサーバーが意図せず実行されるためです。

認証情報の選択

サービスアカウントを推奨します。明示的に追加したプロパティのみを参照でき、サービスアカウントを無効化しても、誰かの Google アカウントには影響しません。Search Console の「設定」→「ユーザーと権限」で client_email を追加するか、verify_site を使って所有権を付与してください。なお、Indexing API には完全なユーザー権限ではなく、所有者権限が必要です。

OAuth2 リフレッシュトークンは、同意したユーザーとして動作し、そのユーザーが参照できるすべての情報を参照できます。スコープは同意した時点で固定され、後から拡張することはできません。

読み込むツールの選択

表示されるツールはどれもリクエストごとにコンテキストを消費します。また、モデルは21個から選ぶより、5個から選ぶほうがはるかに確実です。リストを絞り込む変数は2つあります。

GSC_ALLOW_TOOLS=essential          # the curated five
GSC_ALLOW_TOOLS='list_*,get_site'  # exact names, or one trailing *
GSC_DENY_TOOLS='delete_*'          # subtracted from whatever allow left

essential は list_sites、get_site、list_sitemaps、 query_search_analytics、inspect_url です。プロパティを確認するのに必要なものだけで、プロパティを変更するものはありません。

どのツールにも一致しないエントリーがあると、実際の名前の一覧とともにサーバーが停止します。 誤記が無視されると、原因を示すものが何もないまま tools/list からツールが欠落します。環境変数のせいでツールが使えないと誰も気づかないでしょう。

これらのサーバーを複数同時に実行する場合は、mcp-hub も選択肢になります。/hub エンドポイントを使うと、各サーバーのツールが6つのメタツールに置き換わります。

リストを絞り込むと、認証情報も絞り込まれます。このサーバーがリクエストする OAuth スコープは、実際に登録されたツールをもとに決まるため、Indexing ツールを拒否されたサーバーが Indexing スコープを要求することはありません。

インストール

Claude Code

claude mcp add google-search-console -- npx -y @ni-c/google-search-console-mcp

Claude Desktop

{
  "mcpServers": {
    "google-search-console": {
      "command": "npx",
      "args": ["-y", "@ni-c/google-search-console-mcp"],
      "env": {
        "GSC_SERVICE_ACCOUNT_KEY_FILE": "/path/to/key.json",
        "GSC_SITE_URL": "sc-domain:example.com"
      }
    }
  }
}

Codex

[mcp_servers.google-search-console]
command = "npx"
args = ["-y", "@ni-c/google-search-console-mcp"]

[mcp_servers.google-search-console.env]
GSC_SERVICE_ACCOUNT_KEY_FILE = "/path/to/key.json"
GSC_SITE_URL = "sc-domain:example.com"

Docker

docker run --rm -i \
  -v /path/to/key.json:/key.json:ro \
  -e GSC_SERVICE_ACCOUNT_KEY_FILE=/key.json \
  -e GSC_SITE_URL=sc-domain:example.com \
  ghcr.io/ni-c/google-search-console-mcp

mcp-hub 経由

ローカルプロセスを起動できないクライアント（ChatGPT コネクター、ウェブ版 Claude、Cursor、LibreChat など）は、mcp-hub 経由で google-search-console-mcp に接続できます。1つのコンテナーが複数の stdio MCP サーバーを Streamable HTTP 経由で提供し、単一のパスワードによる OAuth 2.1 ログインと、OAuth に対応していないクライアント向けの長期間有効なトークンを備えています。/hub エンドポイントを使うと、各サーバーが6つのメタツールの背後に置かれます。そのため、モデルのコンテキストに N×個のツールスキーマを含めることなく、1つのコネクターからすべてのサーバーにアクセスできます。また、両方のプロトコル改訂版に対応しているため、このサーバーが質問をすると、遠隔地にいる担当者まで届きます。

/config/mcp.json は Claude Code の形式を使うため、エントリーはすでにお使いのものと同じです。

{
  "mcpServers": {
    "google-search-console": {
      "command": "npx",
      "args": ["-y", "@ni-c/google-search-console-mcp"],
      "env": {
        "GSC_SERVICE_ACCOUNT_KEY": "…",
        "GSC_SITE_URL": "sc-domain:example.com"
      }
    }
  }
}

ここでの allowTools と denyTools は、サーバーごとに適用するハブ独自のフィルターです。env の *_ALLOW_TOOLS とは異なります。その違いと、そこで起こりうる間違いについては、クライアントガイドをご覧ください。

ツール

GSC_SITE_URL が設定されている場合、site_url を受け取るツールでは、どのツールでも site_url は省略可能です。

すべてのツールは outputSchema を宣言し、テキストブロックとともに structuredContent で応答するため、クライアントは文章を解析せずに結果を利用できます。 query_search_analytics はテキストブロックにレンダリング済みの表を残し、構造化データ側に行データを格納します。文章で応答していた6つのツールも、フィールドを返すようになりました。

Google のデータを報告するすべてのツールは、フィールドとして untrusted: true と source: "search-console" を含みます。「検索データにすぎない」というのは、まさに誤った考え方です。検索クエリは一般の人が Google に入力した文字列であり、ページタイトルはクロールされたサイトから取得されます。このマーカーが付かないツールは6つあります。回答が、このサーバーに与えられたプロパティと、サーバーが確認した事実だからです。add_site、delete_site、submit_sitemap、submit_sitemaps、delete_sitemap、unverify_site が該当します。

プロパティと所有権

ツール	機能
setup_site	4 つのセットアップ手順のうち、プロパティで未完了の手順と、設置する DNS レコードまたはメタタグを報告します。変更は行いません
list_sites	この認証情報で参照できるすべてのプロパティと、その権限レベルを一覧表示します
get_site	1 つのプロパティを取得します。2 つの表記のどちらが存在するかを確認できます
add_site	プロパティを追加します。所有権の確認は行いません
delete_site 👤	プロパティとその履歴を削除します
list_verified_sites	この認証情報で所有権が確認されたサイトと、すべての所有者を一覧表示します
get_verified_site	不透明なリソース ID で、そのうちの 1 つを取得します
get_verification_token	トークンと、その正確な設置場所を取得します。所有権については何も主張しません
verify_site	設置されたトークンを確認し、所有権を記録します
unverify_site 👤	所有権を放棄します
update_site_owners	所有者リストを置き換えます。method: "patch" は PATCH を使用しますが、動作は同一です

サイトマップ

ツール	機能
list_sitemaps	送信済みサイトマップと、ダウンロード時刻、URL 数、エラーを一覧表示します
get_sitemap	1 つのサイトマップを取得します。送信時のエラーが実際に表示される場所です
submit_sitemap	1 つのサイトマップを送信または更新します。専用の更新呼び出しはありません
submit_sitemaps	1 回の呼び出しで最大 50 件を送信し、各項目の結果を返します
delete_sitemap 👤	1 つ削除します

検索アナリティクスとインデックス登録

ツール	機能
query_search_analytics	パフォーマンス レポートを取得します。任意のディメンション別のクリック数、表示回数、CTR、掲載順位を、フィルターや相対期間とともに確認できます
inspect_url	1 つの URL について Google が把握している情報（インデックス登録状況、正規 URL、クロール時刻、リッチリザルト）を取得します
inspect_urls	最大 20 件の URL を判定結果に要約して取得します
get_indexing_status	URL のインデックス登録 API 通知履歴を取得します
request_indexing	URL が変更されたことを Google に通知します。JobPosting ページと BroadcastEvent ページにのみ作用します

意図的に公開していない機能

urlTestingTools.mobileFriendlyTest は現在も Google のディスカバリー ドキュメントに記載されていますが、 その背後にあるサービスは 2023 年 12 月に停止されました。この機能のツールを作っても エラーを返すことしかできないため、用意していません。

安全性

4 つの操作ではユーザーに確認を求めます。 delete_site、delete_sitemap、 unverify_site、update_site_owners は、クライアントが対応している場合、MCP エリシテーションを通じて実際のダイアログを表示します。モデルがユーザーに代わって 回答することはできません。対応していない場合は、最初の呼び出しを拒否して、指定された 引数に厳密にひも付けられた有効期間の短いトークンを返し、誰かが承認したかのように 装わず、その旨を伝えます。どちらの場合も、承認は対象のプロパティにひも付けられるため、 あるプロパティに対して発行された承認を別のプロパティに対して再利用することはできません。 update_site_owners がこの一覧に含まれるのは、指定する一覧が操作後の所有者全員を表すためです。 形式が正しい呼び出しを 1 回行うと、ほかの全員が削除され、この機能では元に戻せません。 ELICITATION=false は意図的に代替手順を使用しますが、保護措置を解除することは ありません。ユーザーへの確認を 参照してください。

API からの情報はすべて信頼できないものとして扱われます。 検索クエリは、一般のユーザーが Google に入力した文字列です。ページタイトルやクロール診断情報は、クロール対象のサイトを 運営する人に由来します。モデルに指示どおりの操作をさせたい人は、ページタイトルに指示を 書き込み、クロールされるのを待つことができます。確認プロンプトの 2 つの文は、サーバーが 導出した値のみから構成されます。サイトマップ URL や所有者一覧は、その下にデータとして 引用されます。

許可リストに例外はありません。 GSC_ALLOWED_SITES は、ツールでプロパティを指定する すべての箇所で適用されます。また、プロパティを指定しない 2 つの形式にも個別に適用されます。 Indexing API ツールは、Search Console がプロパティの範囲を決める方法に従ってページ URL を 一覧と照合し、検証ツールは操作の前に不透明なリソース ID をプロパティに解決します。 どちらの一覧も許可リストに絞り込み、除外した項目数を伝えます。

読み取り専用はツール層より下で適用されます。 GSC_READ_ONLY=true の場合、書き込み ツールを登録しないだけでなく、webmasters ではなく webmasters.readonly を要求するため、 ツールが書き込みを試みたとしても実行できません。

認証情報が出力に漏れることはありません。 起動後は環境から削除され、リダイレクト先に 送信されることもありません。拒否された値はそのまま表示せず、説明だけを示します。これは、 誤って GSC_ALLOW_TOOLS、GSC_SITE_URL、ELICITATION に貼り付けられたキーの場合も、 ヘッダーになる前にチェックされるアクセストークン自体の場合も同様です。

Google からの応答は、定められた形式に沿って検証されます。 本文を読み取る前に応答の ステータスを判定し、結果として保証するすべてのフィールドを境界で検証します。オブジェクト ではない行は破棄され、null のサイトブロックはサイトとして扱われず、空の 200 は空の レコードとして扱われます。また、出力時にテキストから制御文字を除去します。結果は両方の チャネルで上限を設け、呼び出し元の文字列にも長さの上限を設けます。バッチ呼び出しは 2 分後に停止し、どこまで処理できたかを伝えます。 セキュリティを参照してください。

ドキュメント

詳細なガイド、ツールリファレンス、セキュリティに関する注意事項は、 google-search-console-mcp.ni-c.de に あります（ソースは docs/ にあります）。

開発

npm install
npm test            # no network — every test runs against a stubbed fetch
npm run lint
npm run build

CONTRIBUTING.mdを参照してください。

リリース

CHANGELOG.md を更新し、package.json と server.json のバージョンを上げてから、 署名付きタグを push します。

git tag -s v0.1.0 -m 'v0.1.0' && git push origin main v0.1.0

release.yml はテストスイートを実行し、信頼できるパブリッシャーを通じて来歴情報付きで npm に公開し、マルチアーキテクチャイメージを GHCR に push して、MCP レジストリの エントリを更新します。

コントリビューション

Issue、ディスカッション、プルリクエストを歓迎します。CONTRIBUTING.mdを 参照してください。脆弱性については、公開の Issue ではなく 非公開での報告を ご利用ください。ポリシーは SECURITY.md に記載されています。

ライセンス

MIT © Willi Thiel