gsc-indexer-mcp

Google Search Console MCP サーバー

Claude やその他の AI エージェントに、Google Search Console を実際に操作する機能を提供する MCP サーバーです — プロパティの一覧表示、URL がインデックスに登録されているかの確認、Google に除外されたページの特定、URL 検査の一括実行、サイトマップの送信、インデックス登録のリクエスト、検索アナリティクスの取得を、すべて会話から実行できます。

SEO の実務担当者が、プロパティごとに手作業でインデックス状況を確認したり、サイトマップを送信したりすることにうんざりしている場合や、代わりにそれを実行できる AI エージェントのために作られています。

shahidali.co/tools/gsc-mcp はプロジェクトページです。このリポジトリを開いたことがない人向けに、同じインストール手順、ツール一覧、実際のクォータルールを掲載しています。

目次

• エージェントに追加する — Claude Code、Cursor、VS Code、LM Studio 用のワンライナー
• プロジェクトのステータス — 検証済みの内容と、検証したプラットフォーム数
• ツール — このサーバーに登録されている 15 個のツール
• クォータ管理が難しい理由
• インデックスに登録されていないページを見つける · 理由コード
• URL を送信する · 使用するツール · 初回送信の前に
• 要件
• インストール · OAuth クライアントは自動で処理されます · 独自の OAuth クライアントを使用する
• はじめに — 初回実行、サインイン、ブラウザー拡張機能
• 開発 · アーキテクチャ
• プライバシー — お使いのマシンから送信される情報と、送信されない情報
• 既知の制限 — クライアントのプロパティで使用する前にお読みください
• コントリビューション · ライセンス

エージェントに追加する

Claude Code では、次のコマンドを 1 つ実行するだけです。

claude mcp add gsc -- uvx gsc-indexer-mcp

MCP に対応するその他のクライアントでは、手動で設定します。設定全体は次のとおりです。

{
  "mcpServers": {
    "gsc": { "command": "uvx", "args": ["gsc-indexer-mcp"] }
  }
}

uvx はパッケージを事前のインストールなしで取得して実行するため、上記のボタンはどれもワンライナーになっています。同じ内容の .mcp.json がこのリポジトリに含まれているため、リポジトリをクローンするだけでも準備できます。

これらの設定に API キーを含める必要はありません。初めて gsc_setup() を呼び出すときに、ブラウザーで一度サインインします。OAuth クライアントは自動で処理されますを参照してください。

---

プロジェクトの状況

ベータ版です。すべての機能が接続され、1つのオペレーティングシステム上で、1人のユーザーによって、実際の Google アカウントを使った動作が確認されています。

0.1.0 ではプレリリースのサフィックスを外し、pip install で --pre を指定しなくてもインストールできるようにしました。これは利用範囲を広げるための判断であり、成熟度を示すものではありません。このプロジェクトには、作者以外の方からのバグ報告が必要です。pip がデフォルトではインストールを拒否するパッケージでは、報告は集まりません。大切なプロパティに接続する前に、CHANGELOG.md の既知の問題を確認してください。特に、Google から一時的なレート制限を受けると、現在はバッチ全体が終了します。バグ報告をお待ちしています。ぜひ報告してください。

サーバーには15個のツールが登録されており、実際の MCP クライアントセッションに接続し、すべてのツールが説明付きで応答することを確認する、ワイヤーレベルのスモークテストで検証されています。ストレージ、クォータ管理、OAuth、設定が、その基盤となっています。Windows 上で実際の Google アカウントを使ったサインインの手順を確認しました。確認時に見つかった不具合も記録している docs/manual-smoke.md をご覧ください。その後、送信機能では実際のブラウザーを操作し、Chrome と Brave で実際のプロパティに対する Request Indexing 呼び出しを Google が確認しました。これは1つのプラットフォーム、1人のユーザーによる検証であり、それに関する自動アサーションはすべて依然としてフェイクに対して実行されています。これによって確認できること、できないことについては、「既知のギャップ」をご覧ください。

マイルストーン	範囲	状態
1. 基盤	パス、ログ記録、SQLite ストア、クォータエンジン、OAuth + PKCE、設定	完了
2. MCP サーフェス	以下のツールを MCP 経由で公開	完了
3A. オンボーディング	ガイド付きサインイン、ブラウザー／プロファイル検出、ブリッジ拡張機能	完了
3B. 送信	ブラウザー操作による Request Indexing、ジョブ制御	Windows 上で実稼働環境にて検証済み
4. レポート	インデックス登録状況の検出と監査	Windows 上で実稼働環境にて検証済み

リリース済みバージョンと各バージョンの変更内容については、CHANGELOG.md をご覧ください。Windows 以外のプラットフォームでも上記のマイルストーンが検証された際に知りたい場合は、リポジトリをウォッチまたはスターしてください。

ツール

現在、MCP サーバーに実装・登録されているツール：

ツール	機能
gsc_list_sites	アカウントからアクセスできるすべての Search Console プロパティを一覧表示します
gsc_doctor	認証、設定、環境に関する問題を診断します
gsc_check_status	URL Inspection API を使って1つ以上の URL のインデックス状況を確認します（読み取り専用。Request-Indexing の枠を消費しません）
gsc_quota	プロパティごとの、今日残っている Request-Indexing と URL Inspection の枠を表示します
gsc_performance	Search Analytics のクリック数、表示回数、CTR、掲載順位を表示します
gsc_submit_sitemaps	プロパティにサイトマップを送信または再送信します
gsc_setup	サインインとセットアップの手順を案内します。冪等で、次のステップを1つだけ返します
gsc_detect_browsers	ブラウザー操作による送信に使う、インストール済みブラウザーとプロファイルを検出します
gsc_use_browser	検出機能の推奨を上書きして、操作するブラウザープロファイルを固定します
gsc_request_indexing	最大5件の URL を、1件ずつインデックス登録に送信します。完了まで数分かかります — URL の送信をご覧ください
gsc_start_indexing_job	任意の数の URL を対象とする送信処理をバックグラウンドジョブとしてキューに登録し、すぐに戻ります
gsc_job_status	1つの送信ジョブ、または直近の送信ジョブの進行状況と状態を表示します
gsc_stop_job	実行中の送信ジョブに対し、処理中の URL が完了した後に停止するよう要求します
gsc_find_unindexed	プロパティ内の URL のうち、インデックス登録されていないものとその理由を特定します — インデックス登録されていないページの確認をご覧ください
gsc_audit	ローカルストアから取得した、プロパティの現在のインデックス登録状況を表示します。クォータは消費しません

クォータ管理が難しい理由

この分野の多くのツールは Google の上限を正しく把握できておらず、その結果、リクエストを制限されると原因を検知に求めます。重要な上限はどちらもアカウント単位ではなくプロパティ単位です。

上限	値	仕組み
インデックス登録のリクエスト	プロパティあたり約 11 枠	ローリング方式 — 各枠は使用から 24 時間 + 1 分後に再び利用可能になります
URL 検査	プロパティあたり 1 日 2,000 件	毎日リセット
URL 検査	プロパティあたり 1 分 600 件	レート制限

プロパティごとに独立しているため、8 つのプロパティがあれば、予算も 8 つに分かれます。このサーバーは 1 日の合計数を数えるのではなく、枠を個別に追跡するため、次の枠が利用可能になる正確な時刻を把握できます。また、競合が起こり得る場合には意図的に少なくではなく多めに数えます。少し待つほうが、Quota Exceeded で完全に拒否されるよりも低コストだからです。

インデックス登録されていない URL を見つける

gsc_find_unindexed は、プロパティに登録されたサイトマップ、ローカルストアにすでにある URL、またはその両方から候補 URL を集め、最後の検査結果が古くなった URL を検査し、インデックス登録されていない各 URL とその理由を報告します。limit が制限するのは検査する URL の数であり、結果に含まれる数ではありません。検査には予算を使うため、出力だけを絞り込む上限では、破棄する回答に全コストを支払うことになります。上限付きの実行で対象になる URL は、古さではなくストア独自の URL 順（アルファベット順）に従います。そのため、上限付きの実行は、古いものから優先する一括処理ではなくサンプルになります。

gsc_audit は、ストアだけを使って同じ質問に答えます — HTTP 検査は行わず、予算も消費しません。これはある時点での状態を示すもので、最後の検査でわかったことを報告し、as_at と stale 件数を含めて、その情報がどれほど古いかを判断できるようにします。変化量を示す数値は意図的に含めていません。

理由コード

理由コードは10 種類です。各行の submitting_helps は、gsc_request_indexing を呼び出す前に対応すべきかどうかを示します。

理由	submitting_helps	意味
discovered-not-indexed	yes	Google は URL を認識していますが、まだクロールしていません
unknown-to-google	yes	Google はその URL を見たことがありません
crawled-not-indexed	yes	Google はクロールしましたが、インデックス登録しないことを選びました — その後に改善して送信してください
404	no	URL が「見つかりません」を返します
redirect	no	URL が別の場所にリダイレクトします
noindex	no	ページまたはそのレスポンスに noindex ディレクティブがあります
soft-404	no	200 を返しますが、エラーまたは空のページとして認識されます
robots-blocked	no	robots.txt が URL をブロックしています
duplicate	no	Google が別の正規 URL を選びました
alt-canonical	no	自身の正規 URL を指す代替ページです — 対応は不要です

設計メモにある 8 種類のコード一覧を読んで、ここでは 10 種類あると気づいた場合、追加された 2 つは discovered-not-indexed と unknown-to-google です。これらは意図的に crawled-not-indexed と分けています。3 つとも「クォータ枠を使えば状況が変わるか」という問いには はい と答えられますが、「最初に何をすべきか」という問いへの答えは異なり、対応の判断にはその違いが重要です。discovered と unknown は、Google がまだ評価していないページです — まだ取得されていないため、送信することが解決策そのものです。crawled-not-indexed は、取得されたものの採用されなかったページです。再クロールによって判断が覆ることはありますが、内容を変えずに再送信しても、同じ結果に至る再クロールになるだけです。ページを改善してから送信してください。

枠はプロパティあたりローリング 1 日につきおよそ 11 個で、使い切ると取り戻せません。また、実際のサイトでは crawled-not-indexed が通常、最大のグループです。submitting_helps: true は、その枠が効果を発揮する可能性があるという意味であり、今日その枠を使うべきだという意味ではありません。

検査に失敗した場合や、再確認しても結果を確定できなかった場合など、状態を確認できなかった URL は、インデックス登録されていない URL としてではなく undetermined として報告されます。証拠がないことは、判断が下されたことを意味しません。

URL の送信

Google には、このようなツールで使用できるインデックス登録をリクエストする API がないため、送信はご自身のブラウザーを通じて行われます。gsc_setup 中にペアリングしたプロファイルに読み込まれたブリッジ拡張機能が、実際の Search Console セッションで「インデックス登録をリクエスト」をクリックします。利用を始める前に知っておくべき影響が 3 つあります。

時間がかかりますが、その遅さが重要な機能です。 送信の間隔は 130～180 秒です。この間隔は仮の値でもバグ報告の対象でもなく、長時間の実行でスロットリングを引き起こさないことが実証されています。そのため、5 件の URL では実時間で最大 15 分かかり、実行するツールはその間ずっとブロックされます。

割り当て量はプロパティごとで、少量です。 プロパティごとに約 11 件の枠があり、直近 24 時間のローリングウィンドウで管理されます。各枠は使用から 24 時間と 1 分後に個別に回復し、午前 0 時に一斉に回復するわけではありません。プロパティごとに独立した割り当て量があります。まず gsc_quota を呼び出し、free ではなく spendable_free に基づいて処理してください。spendable_free は、設定で確保した daily_reserve を差し引いた値です。使用済みの枠は取り戻せず、取り消しもできません。

一度に実行できるのは 1 件だけです。 ブリッジは実際のプロファイル内の単一のブラウザータブを操作し、固定のローカルポート 1 つで待ち受けます。そのため、実行中に 2 件目を開始すると、キューに入るのではなく明示的に拒否されます。これは両方向に適用されます。ジョブまたは gsc_request_indexing の呼び出しが実行中のときの gsc_start_indexing_job と、ジョブの実行中の gsc_request_indexing のどちらも拒否されます。

使用するツール

状況	使用するツール	理由
URL が 1～5 件で、待つことができる	gsc_request_indexing	同期処理です。すべての URL の結果を返します。上限は 5 件です。設定の sync_submit_cap で上限を下げることはできますが、上げることはできません。
URL が 5 件を超える、またはセッションをすぐに使える状態に戻したい	gsc_start_indexing_job	すぐに job_id を返し、処理はバックグラウンドで続行されます。上限はありません。
ジョブの実行中	gsc_job_status	進行状況、URL ごとの結果、およびワーカーが処理を続けているかを確認できます。引数なしで呼び出すと、直近のジョブの状態を報告します。
終了したいジョブがある	gsc_stop_job	実行中の URL の処理が終わった後に停止します。URL の処理途中では停止しません。送信済みの URL は枠を消費しており、台帳の行を実際の結果で確定する必要があるためです。

問題が発生した場合の実行動作

すでに拒否しているサーバーに対して残りのバッチを無駄に実行するのではなく、実行は早期に停止します。quota_exceeded、CAPTCHA、レート制限、またはサインアウト状態になると、実行は終了します。結果の stopped_early と stop_reason にその旨が記録され、未試行の URL の枠は消費されません。この方法で終了したジョブの状態は stopped_throttled になり、手動で停止したジョブの状態は stopped_user になります。

既知のどのプロパティにも割り当てられなかった URL は no_property となり、使用可能な枠がなかった URL は no_quota となります。どちらもブラウザーには到達せず、何も消費しません。対処方法が異なるため、失敗とは分けて報告されます。前者の場合は gsc_list_sites を実行し、後者の場合は待機してください。

ジョブの実行中にサーバーが再起動すると、次回起動時にそのジョブの行は failed として終了し、開いたままの送信行はプロパティの台帳に照らして確定されます。暗黙に再開されることはありません。バックグラウンドワーカーは、それを所有するプロセスが終了すると動作を続けられません。

初回送信の前に

ペアリングしたブラウザープロファイルに拡張機能を読み込み、サーバーが操作できるブラウザーを使用する必要があります。gsc_setup で両方を設定し、gsc_doctor で再確認できます。ブラウザーが閉じている場合は、auto_launch_browser（デフォルトで有効）がブラウザーを開きます。すべてのペアの初回実行では、拡張機能とブリッジをペアリングするため、ブラウザーウィンドウを手前に表示する必要があります。

必要条件

• Python 3.11 以降
• Search Console のプロパティを持つ Google アカウント
• Chromium ブラウザー — Chrome、Brave、Edge、Vivaldi、Opera、Chromium のいずれか。gsc_setup は既存のプロフィールのいずれかにブラウザー拡張機能を読み込むため、 これなしでセットアップを完了する方法はありません。Firefox と Safari は Chromium ではないため、動作しません。
• Google Cloud のセットアップは不要です。gsc_setup はこのプロジェクトに 同梱されている OAuth クライアントを取得します。独自のクライアントを 指定することもできます。詳しくは「インストール」をご覧ください。

インストール

配布パッケージ名は gsc-indexer-mcp です。indexer にご注意ください。PyPI にある単なる gsc-mcp は別の作者による無関係なプロジェクトなので、その名前をインストールすると、 他の人のサーバーを取得してしまいます。このパッケージ内では、インポートパッケージ、 コンソールスクリプト、設定ディレクトリのすべてで、引き続き gsc_mcp を使用します。

pip install gsc-indexer-mcp

0.1.0a6 までのバージョンはプレリリースであり、--pre が必要でした。 0.1.0 以降では不要です。

あるいは、インストールを省略して uvx gsc-indexer-mcp に必要なときに取得させることもできます。 このページ上部のボタンでは、この方法を使用しています。

最新のリリース からホイールを取得することもできます。このホイールには以下で説明する違いが1つあります。 PyPI のビルドでは初回セットアップ時に OAuth クライアントをダウンロードしますが、 こちらには OAuth クライアントが含まれています。

また、何かを変更する予定がある場合は、チェックアウトからインストールできます。

git clone https://github.com/Mrshahidali420/google-search-console-mcp.git
cd google-search-console-mcp
python -m venv .venv
.venv/Scripts/python -m pip install -e .   # POSIX: .venv/bin/python

OAuth クライアントは自動的に処理されます

Google Cloud プロジェクトは必要ありません。gsc_setup() は、環境変数、 リリースホイールに組み込まれたクライアント、そしてこのプロジェクトに同梱されている クライアントの初回ダウンロード（設定ディレクトリにキャッシュ）の順に探します。 ソースをチェックアウトした場合は3番目の方法が使われ、初回実行後はすべてオフラインで利用できます。

追跡対象のソースには、意図的にクライアントを含めていません。公開リポジトリにコミットされた シークレットは Git の履歴に永久に残り、GitHub は Google のクライアントシークレットを Google に報告するため、Google がそれを無効にし、すべてのユーザーに一斉に影響する可能性があります。 そのため、代わりにリリースアセットとして配布し、ビルド時に注入します。 仕組みについては docs/google-cloud-oauth.md をご覧ください。 率直に言うと、このアセットは公開されており、ホイールと同様に誰でも読むことができます。 これによって得られるのはシークレット性ではなくローテーションです。インストールされた アプリのセキュリティは、このプロジェクトが使用する PKCE によって確保されます。

独自の OAuth クライアントを使用する場合

任意です。同意画面に独自のアプリ名を表示したい場合や、組織で独自のクライアントが必要な場合に設定すると便利です。GSC_MCP_CLIENT_ID と GSC_MCP_CLIENT_SECRET を設定すると、リリースビルドでもソースチェックアウトでも、上記のすべての設定より優先されます。

これらの設定はすべて Google Cloud Console で行います。無料で、所要時間は約 5 分です。手順は順番どおりに進めてください。手順 4 は省略されがちですが、省略すると最後に失敗します。

1. プロジェクトを作成します。 上部バーのプロジェクトのドロップダウンから → 新しいプロジェクト を選択します。名前は自由です。作成が完了するまで待ち、その後、ドロップダウンでそのプロジェクトが選択されていることを確認してください。以下の設定はすべて、選択中のプロジェクトにのみ適用されます。

2. Search Console API を有効にします。 コンソールの検索バーで「Search Console API」を検索し、開いてから 有効にする をクリックします。これを行わないと、すべての呼び出しで API が無効であることを示す 403 が返されます。

3. OAuth 同意画面を設定します。 左側のメニューで API とサービス → OAuth 同意画面 を選択します。

   • ユーザータイプ：外部。（「内部」は Workspace アカウントでのみ使用でき、アプリが自組織に制限されます。）
   • アプリ名：任意です。表示されるのはあなただけです。
   • ユーザーサポートのメールアドレスとデベロッパーの連絡先メールアドレス：ご自身のアドレスを指定します。
   • ここでスコープを追加する必要はありません。このサーバーはサインイン時にスコープを要求するため、この画面で追加しても付与される内容は変わりません。
   • 最後まで保存します。

4. アプリを公開するか、自分をテストユーザーとして追加します。どちらでも機能しますが、公開するほうがおすすめです。ここは省略されがちな手順です。

   新しいアプリはすべて テスト中 のステータスで始まり、Google は登録済みのテストユーザーにのみサインインを許可します。それ以外のユーザーは同意画面で 403: access_denied を受け取ります。これはプロジェクトの作成、API の有効化、クライアントの作成、環境変数の設定、gsc_setup の実行をすべて済ませた後に起きます。それ以前に警告は表示されません。また、テスト中のアプリでは更新トークンが 7 日ごとに期限切れになるため、1 週間後にサインインできなくなります。ここでのバグのように見えますが、そうではありません。

   Google では Search Console の両方のスコープが非機密に分類されるため、公開に費用はかかりません。本人確認も、セキュリティ評価も、ユーザー数の上限もありません。対象ユーザー → 公開ステータス → アプリを公開 を選ぶと、上記の両方の問題が解消されます。

   テスト中のままにしたい場合は、テストユーザー（新しいコンソールでは 対象ユーザー → テストユーザー）を開き、Search Console プロパティを所有する Google アカウントのアドレスを追加します。自分のアカウントでは無期限に使用できますが、7 日ごとに再度サインインする必要があります。

5. OAuth クライアントを作成します。 API とサービス → 認証情報 → 認証情報を作成 → OAuth クライアント ID の順に選択し、アプリケーションの種類として デスクトップアプリ を指定します。表示されるクライアント ID とクライアントシークレットをコピーしてください。シークレットが表示されるのは一度だけですが、いつでも別のクライアントを作成できます。

   適切な種類はデスクトップアプリです。このサーバーは 127.0.0.1 へのループバックリダイレクトを使ってサインインしますが、この種類ではそれが許可されています。「ウェブアプリケーション」は選択せず、リダイレクト URI も手動で追加しないでください。

6. サーバーを起動する前に、以下の 2 つの環境変数を設定します。設定しない場合、Google との通信が必要なツールは何も実行せず、{"ok": false, "error": "not_configured", ...} を返します。gsc_list_sites、gsc_check_status、gsc_performance、gsc_submit_sitemaps はすべてこのように動作します。例外は gsc_doctor と gsc_quota の 2 つです。gsc_doctor は引き続き実行され、チェック一覧の 1 行として oauth_client: not ok を報告します。完全に失敗するわけではないため、問題が解決しないときに最初に実行するのに適したツールです。gsc_quota はローカルのみで動作し、OAuth の設定にかかわらず、空のストアでは [] を返します。

export GSC_MCP_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GSC_MCP_CLIENT_SECRET="your-client-secret"
# Windows PowerShell:
#   $env:GSC_MCP_CLIENT_ID = "your-client-id.apps.googleusercontent.com"
#   $env:GSC_MCP_CLIENT_SECRET = "your-client-secret"

MCP クライアントに接続する

インストールしたコンソールスクリプトを MCP クライアントに指定します。Claude Desktop の場合は、claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "gsc-mcp": {
      "command": "C:\\path\\to\\google-search-console-mcp\\.venv\\Scripts\\gsc-mcp.exe",
      "env": {
        "GSC_MCP_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GSC_MCP_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

POSIX では、代わりにコマンドとして .venv/bin/gsc-mcp を使用します。stdio サーバーを起動できるほかの MCP 対応クライアントでも同様に動作します。エントリーポイントは上記でインストールした gsc-mcp コンソールスクリプトで、サーバーは標準の MCP stdio トランスポート（gsc_mcp.server:main）を使用して通信します。

Windows 上で実際の MCP クライアントセッションを通じて実際の Google アカウントを使い、動作を確認しています。Claude Desktop での実行や、macOS または Linux での実行は確認していません。「既知の制限」を参照してください。

はじめに

サーバーをインストールして接続したら、セットアップ全体は 1 つのツールを繰り返し呼び出すだけです。gsc_setup() は冪等です。セッションを再開することはなく、呼び出すたびに状態全体を再読み込みし、次に行うべきことを 1 つだけ返します。ok: true が返されるまでループで呼び出してください。

1. インストールして接続する — 上記のインストールを参照してください。

2. 何もありません。 OAuth クライアントは自動で処理されます。初回実行時に gsc_setup() がダウンロードしてキャッシュします。独自のものを使用する場合に限り、GSC_MCP_CLIENT_ID と GSC_MCP_CLIENT_SECRET を設定してください。

3. gsc_setup() を実行します。 ブラウザーで Google の同意画面を開き、URL も返すため、ヘッドレスマシンでも手動で完了できます。同意したら、もう一度 gsc_setup() を呼び出してください。2 回目の呼び出しでリダイレクトを取得し、トークンを保存して、次の手順に進みます。サインイン情報が呼び出し元に返されることはありません。トークン、認可コード、PKCE 検証子のいずれも返されません。

4. ブリッジ拡張機能を読み込みます。 gsc_setup() は拡張機能の展開先と、読み込むブラウザープロファイルを知らせます。そのブラウザーで拡張機能のページ（chrome://extensions、brave://extensions、edge://extensions など。使用中のブラウザーに対応する正確な URL は gsc_setup() が示します）を開き、デベロッパーモードをオンにして、パッケージ化されていない拡張機能を読み込むを選び、指定されたフォルダーを選択してください。

警告バナーが表示されますが、これは想定どおりです。 この拡張機能は debugger 権限を要求するため、Chromium は拡張機能がブラウザーをデバッグしていることを示す目立つバーを表示し、デベロッパーモードを有効にすると警告が表示される場合があります。この権限は付随的なものではありません。Search Console は、実際のポインター操作によらない「インデックス登録をリクエスト」クリックに対してソフトスロットリングを適用し、合成 DOM クリックではそれに抵触します。そのため、この拡張機能は代わりに Chrome DevTools Protocol を通じて信頼された入力イベントを発行します。これを許可するのが debugger 権限であり、これを許可する唯一の方法です。このバナーは、Chromium が実際の機能を正しく報告しているものです。「これは、たった今インストールした拡張機能です」という意味で受け取ってください。マルウェアを示すものではありません。この拡張機能が接続するのは、host_permissions に含まれる唯一のホストである search.google.com だけです。

5. gsc_doctor() を実行します。 7 つのチェックを順番に行います。oauth_client、token、config、store、properties、browser、extension です。失敗した各チェックには具体的な fix が含まれます。すべて正常に動作しているマシンでの出力例：

{
  "ok": true,
  "checks": [
    {"name": "oauth_client", "ok": true, "detail": "configured", "fix": ""},
    {"name": "token", "ok": true, "detail": "token file present", "fix": ""},
    {"name": "config", "ok": true, "detail": "config valid", "fix": ""},
    {"name": "store", "ok": true, "detail": "schema version 2", "fix": ""},
    {"name": "properties", "ok": true, "detail": "2 properties", "fix": ""},
    {"name": "browser", "ok": true,
     "detail": "Google Chrome / Default is the profile to use", "fix": ""},
    {"name": "extension", "ok": true,
     "detail": "the gsc-mcp bridge extension is installed in Google Chrome / Default at version 1.10.0; whether its background service worker is running is not checked in this milestone",
     "fix": ""}
  ]
}

ブラウザーと拡張機能のチェックについて

この2つは Google アカウントではなくローカルマシンに関するもので、失敗の状況を誤解しやすいため、慎重な表現になっています。

「確認できませんでした」は「インストールされていません」という意味ではありません。 拡張機能のチェックでは、ブラウザー自身の設定ファイルを読み取ります。これらのファイルは、ロック中だったり、書き込みの途中だったり、クラウド同期中だったり、ウイルス対策ソフトによって開かれたままになっていたりすることがよくあります。読み取りができない場合、チェック結果は「質問を確認できませんでした」となり、拡張機能はすでに存在する可能性があると示します。これは、拡張機能が見つからないことを婉曲に伝えているのではありません。対処方法は gsc_doctor() をもう一度実行すること（ブラウザーが起動中なら、先に閉じてください）であり、すでに配置した拡張機能を再インストールすることではありません。同じ違いは gsc_detect_browsers にも当てはまります。その has_extension フィールドは3つの値を取ります。true は存在すること、false はすべての設定ファイルを読み取った結果、拡張機能が見つからなかったこと、null はチェックを実行できなかったことを示します。

Microsoft Edge では、Google アカウントが想定される場面で Microsoft アカウントが報告されることがあります。 Edge は、Chrome が Google アカウントに使用するものと同じファイルの同じキーに、サインイン済みアカウントのアドレスを保存します。しかし、既定ではプロフィールに Microsoft アカウントでサインインします。ディスク上の情報からは、両者を見分けられません。そのため、Edge のプロフィールで見つかったアドレスは、Google アカウントへのサインインを示す証拠にはなりません。また、Microsoft のアドレスが Google アカウントと同じ場合、確実な一致に見えても、実際には確認できていません。ツールは断定を避け、「このプロフィールの Google アカウントへのサインインは確認できませんでした」と Edge のプロフィールを報告します。これを信頼する前に、ご自身で確認してください。Brave、Vivaldi、Opera、通常の Chromium には Google アカウントが一切記録されません。これらについては、読み取るものがないという別の理由で、断定を避けた結果になります。

拡張機能 ID が変わった場合に必要なのは再ペアリングであり、故障ではありません。 この拡張機能にはマニフェストの key が含まれていないため、Chromium は読み込み元の絶対パスをハッシュして ID を生成します。展開先ディレクトリが変わらない限り、ID は安定しています。ディレクトリが移動すると ID は変わります。たとえば、設定ディレクトリの場所が変わるアップグレード、異なる GSC_MCP_HOME の使用、新しいマシンへの移行などが該当します。ID が変わると、拡張機能のチェックは読み込み済みのコピーを認識しなくなり、未インストールとして報告します。故障も破損もしていません。対処方法は、ステップ4と同じように、新しいフォルダーから未パッケージの拡張機能を再度読み込むことです。

extension チェックが緑色でも、登録済みであることを示すだけで、実行中とは限りません。 そのプロフィールで、そのバージョンの拡張機能が読み込まれていることを示します。MV3 のバックグラウンドサービスワーカーが稼働中かどうかは別の問題であり、それを確認できるのはブリッジだけです。送信時にブリッジは接続を待ち、接続がない場合は破棄されたワーカーを起動し、それでも接続できなければ extension_not_connected で失敗します。gsc_doctor が報告するのは、引き続き登録状態のみです。

開発

.venv/Scripts/python -m pip install -e ".[dev]"   # POSIX: .venv/bin/python
.venv/Scripts/python -m pytest -v

アーキテクチャ

gsc_core は MCP に依存しないスタンドアロンエンジンです。そのため、MCP サーバー、CLI、または将来のデスクトップアプリから、変更を加えずに利用できます。

モジュール	担当
gsc_core/paths.py	プラットフォームごとのファイルの保存場所
gsc_core/runlog.py	stderr とファイルへのログ記録。MCP が JSON-RPC 用に予約している stdout には記録しません
gsc_core/store.py	SQLite：サイト、URL、送信、ジョブ、クォータ枠
gsc_core/quota.py	プロパティごとのローリング枠の管理
gsc_core/gauth.py	PKCE S256 を使用した OAuth 2.0、強化されたトークン保管、更新
gsc_core/config.py	検証機能付きのユーザー調整可能な設定
gsc_core/browsers.py	インストール済みの Chromium ブラウザーと、その状態の保存場所
gsc_core/profiles.py	各ブラウザーのプロファイルと、それぞれにサインインしている Google アカウント
gsc_core/pairing.py	ブリッジ拡張機能の展開先と、Chromium が割り当てた ID
gsc_core/bridge.py	ブラウザー拡張機能が接続する localhost WebSocket サーバー
gsc_core/submit.py	URL ごとの送信ループ：振り分け、アトミックなクォータ予約、結果

プライバシー

使用するブラウザープロファイルを特定するため、このツールはお使いのマシン上にあるブラウザー自身のファイル（Local State と各プロファイルの Preferences／Secure Preferences）から、プロファイル一覧とサインイン中のアカウントのメールアドレスを読み取ります。同じファイルは別の目的でもう一度読み取られ、そのプロファイルでブリッジ拡張機能が読み込まれているか、またそのバージョンを確認します。

この読み取りは完全にローカルで行われます。メールアドレスは、どのプロファイルでどのアカウントにサインインしているかを表示するため、メモリー上で使用されます。また、次のことはありません。

• どこにも送信されません。
• このツールによってディスクに書き込まれることはありません。
• いかなるレベルのログにも記録されません。これらのファイルの読み取りに失敗した場合は例外型の名前のみがログに記録されます。これは、メールアドレスや Windows ユーザー名を含むパスが、バグ報告に添付する可能性のあるログファイルに記録されないようにするためです。

このツールがこれらのファイルを書き込み用に開くことはありません。また、プロファイル内で見つかったものも、ご自身が認可したものも含め、メールアドレスがツールから返されることはありません。ツールの結果はトランスクリプトに表示され、サーバーを動かす MCP クライアントによって保持されますが、その動作はこのプロジェクトの管理外です。そのため、プロファイルはブラウザーとプロファイルディレクトリで識別され、それ以外の情報は使用されません。

例外となるパスがひとつありますが、これは意図的なものです。gsc_setup がブリッジ拡張機能がまだ読み込まれていないと判断した場合、結果には拡張機能が展開されたディレクトリが含まれます。Windows では、C:\Users\<your username>\AppData\Roaming\gsc-mcp\extension です。ほとんどのマシンでは、このパスにオペレーティングシステムのアカウント名が含まれます。このパスを返すのは、Chrome の「Load unpacked」でまさにそのフォルダーを選択する必要があり、実行できないセットアップ手順ではプライバシーを守れないためです。ツールが返すパスはこれだけで、必要となる唯一の手順でのみ表示され、ログに記録されることもありません。トランスクリプトにアカウント名を残したくない場合は、その手順を実行した後、トランスクリプトを消去してください。

既知の制約

レビュー担当者がまず確認すべき点を、率直に記します。

• Windows では、icacls が実際に ACL を適用したことを証明するテストはありません。Windows のテストで確認しているのは呼び出しが行われたことだけなので、そこで _harden が何もしなくても、テストスイートは成功します。POSIX の同等機能は現在、プッシュのたびに Linux と macOS で実行されるため、この不足があるのは Windows のみです。
• 送信処理では実際の URL を送信するようになりましたが、テストスイートでは依然としてそれを証明できません。 2026-08-05 時点で、Windows 11 の Chrome と Brave を使い、複数日にわたり複数のプロパティで実際のブラウザーを操作し、「インデックス登録をリクエスト」をクリックして Google がリクエストを確認するところまで実行しました。さらに、Google から実際に拒否されるまでクォータ台帳を使い切るテストも行いました。一方、自動テストで実行されるのは依然としてすべてフェイクのみです。拡張機能ブリッジ、実行間隔の調整、クォータの予約、実行ループ、ジョブワーカーに関するすべてのアサーションは、代用品を対象にしています。つまり、「URL を送信する」ということは現在、CI ではなく手動のログによって裏付けられており、フェイクでは到達できない状態は docs/manual-smoke.md の送信テストに残っています。実際の実行では、テストスイートが見逃した不具合が継続的に見つかっています。まだ不具合が残っていると想定してください。
• サインイン処理は実際に一度だけ、1 台のマシン（Windows 11、Chrome、Python 3.13、2026-08-04）で、9 つのプロパティを持つアカウントを使って実行しました。docs/manual-smoke.md のステップ 1～8 は成功します。1 つのプラットフォームでの 1 回の実行では十分なテスト範囲になりません。自動テストスイート全体が見逃していた不具合が 2 つ見つかりました。これは、サインイン処理を信頼する理由ではなく、macOS と Linux でもう一度実行する理由です。
• doctor は古い拡張機能ビルドを検出できず、現在は検出できるふりをしなくなりました。 Chromium は展開済み拡張機能のマニフェストスナップショットを記録しません。また、このブリッジをインストールする方法は展開済み拡張機能のみです。そのため、ブラウザーが実際に実行しているバージョンをディスクから読み取ることはできません。現在のチェックでは、ディスク上のバージョンを報告し、読み込み済みのバージョンは読み取り不能だと示します。前者を後者として扱うことはありません。これを解決するには、拡張機能からブリッジ経由で chrome.runtime.getManifest().version を報告する必要がありますが、これはプロトコルの変更となるため、ブリッジを実際の送信でテストするまで保留されています。
• ブリッジのポートの既定値は 8765 で、2 つの実行で共有できません。 2 つ目の gsc-mcp プロセスや、そのポートをすでに使用している別のプロセスがあると、バインドに失敗します。現在は拡張機能の接続タイムアウトが過ぎてから原因を拡張機能のせいにするのではなく、数秒以内にポートと対処方法を示して実行に失敗します。ポートを変更する場合（設定の bridge_port）、拡張機能のオプションページでも同じポートを設定する必要があります。両者は対になっており、自動検出はされません。
• macOS と Linux でのブラウザー検出は、ここでも CI でも、実機では一度も実行されておらず、フィクスチャに対してのみテストされています。Mac または Linux マシンでスモークテストのチェックリストを最初に実行する人が、そのテストを実施することになります。
• 現在、実機で gsc_detect_browsers が matches_authorised_account に null を返すのは、保存されたトークンから account_email キーを読み取るフラグに対し、それを書き込む処理がないためです。現在のスコープセットは ID クレームを返さず、同意手順でも認可したアカウントを記録しません。配線は正しいものの、機能していません。このフィールドは「不明」として扱い、「一致しない」とは解釈しないでください。
• extension チェックが報告するのは、拡張機能が登録済みかどうかであり、動作しているかどうかではありません。MV3 ワーカーが稼働しているかどうかを確認できるのはブリッジのみであり、それも送信時に限られます。
• 公開パッケージは PyPI では gsc-indexer-mcp として公開されており、gsc-mcp ではありません。 その名前は別の作者による無関係なプロジェクトのものです。インストールすると、こちらではなくそのプロジェクトのサーバーが入ります。また、2 つの配布経路には重要な違いが 1 つあります。GitHub リリースの wheel にはこのプロジェクトの OAuth クライアントが含まれていますが、PyPI の wheel には意図的に含まれていません（公開インデックスにシークレットを置くと、そのシークレットを無効化することになるためです）。そのため、PyPI からインストールした場合は、最初の gsc_setup() 時に client リリースアセットからクライアントをダウンロードします。どちらの経路もテスト済みですが、同じ経路ではありません。一方の不具合が、もう一方では見つからない可能性があります。
• mcp のバージョンは >=2.0,<3 に固定されています。このサーバーは mcp 2.0 の MCPServer API に基づいています。1.x では FastMCP という名称で、2 つの API 形式には互換性がありません。そのため、このパッケージは現在、依然として mcp<2 を必要とするものと明示的に競合します。これは、旧バージョンで設定されていた <2.0 の上限が引き起こした競合と逆の関係です。

貢献

貢献を心から歓迎します。イシュー、プルリクエスト、バグ報告、ドキュメントの修正など、どんなものでも歓迎です。まずはCONTRIBUTING.mdをご覧ください。最初に取り組むのに適したイシューは、「既知の不足点」に記載されている CI の各環境です。

今、最も役立つ貢献は、Windows 以外のマシンからのバグ報告です。 ここにあるものはすべて、1 人が 1 つのオペレーティングシステム上で手作業でテストしています。既知の不足点をご覧ください。

• バグを報告 · 機能をリクエスト
• セキュリティポリシー — トークン、OAuth、またはローカルブリッジに関する報告は、非公開でお寄せください。
• 行動規範

ライセンス

Apache 2.0 への将来的な移行条項を含む Functional Source License 1.1（FSL-1.1-ALv2）。

簡単に言うと、利用、変更、貢献、クライアントの仕事での実行は自由ですが、これをもとに競合製品を販売することはできません。 各リリースは公開から 2 年後に Apache 2.0 に移行するため、ここにあるものが永久に利用できなくなることはありません。