gsc-mcp-connector

セルフホスト型 Google Search Console MCP サーバー。Cloudflare Workers に 15 分でデプロイ可能。ChatGPT、Claude、または MCP 対応クライアントに接続し、自然言語で GSC データをクエリできます。

このプロジェクトが提供するもの

デプロイ後、プライベートな MCP エンドポイントが得られ、AI アシスタントに以下の 4 つのツールを公開します:

• list_sites — 認証済みユーザーがアクセス可能なすべてのプロパティを検出

• query_search_analytics — クリック数、インプレッション数、CTR、掲載順位。クエリ / ページ / 国 / デバイス / 検索表示 / 日付でフィルタ可能

• inspect_url — URL Inspection API の完全な出力（インデックス状況、正規URL、モバイル、AMP）

• list_sitemaps — 送信済みのすべてのサイトマップとその処理状況

あなたが「過去28日間とその前の28日間で、クリック数の減少が最も大きかった50のクエリはどれですか？」と尋ねると、アシスタントがデータを取得し、差分を計算し、分析を記述します。もう SQL エクスポートは必要ありません。

Related MCP server: gsc-mcp-connector

仕組み

ChatGPT/Claude  ──OAuth──▶  Your Worker  ──OAuth──▶  Google
                                 │
                                 └─ holds your Google refresh_token
                                    (encrypted, in OAuth grant props)

2 つの OAuth チェーン:

1. MCP クライアント → Worker: ChatGPT/Claude が Worker に対して OAuth 2.1 + PKCE を実行します。ログイン UI は、デプロイ時に設定した静的な「アクセスキー」（コネクタゲート）の入力を求めます。

2. Worker → Google: アクセスキーの確認後、ユーザーは Google の同意画面にリダイレクトされ、webmasters.readonly を許可します。結果として得られたリフレッシュトークンは OAuth 認可に保存され、ツール呼び出しのたびに Worker が新しいアクセストークンを取得して GSC を呼び出します。

ユーザーの Google アカウントがアクセスを制御します。サービスアカウントは不要、GSC のユーザー管理の手間も不要、権限反映の遅延もありません。

前提条件

Cloudflare Workers の無料枠（1日10万リクエスト）は個人の SEO 利用で十分です。有料の Cloudflare プランは不要です。

クイックスタート（約15分）

1. Worker をデプロイする

この README 上部の Deploy to Cloudflare ボタンをクリックしてください。Cloudflare がリポジトリをあなたのアカウントにクローンし、依存関係をインストールし、https://gsc-mcp-connector.<your-subdomain>.workers.dev のような公開 URL を発行します。

注: この時点で、MCP_BEARER_TOKEN、GOOGLE_OAUTH_CLIENT_ID、GOOGLE_OAUTH_CLIENT_SECRET の入力を求められます。Google のものはまだ用意できていません — MCP_BEARER_TOKEN には適当なランダムな16進文字列を入力し（後で変更可能）、Google の2つのフィールドには何でも貼り付けてください。これらは手順4で適切に設定します。

ボタンを使わずに進めたい場合は、リポジトリをローカルにクローンし、npm install を実行し、npx wrangler deploy を実行してください。

デプロイ後、Worker URL をメモしてください。手順3と手順5の両方で必要になります。

2. コネクタのアクセスキーを生成する

これは静的なランダム文字列で、Google OAuth の前にゲートとして使用されます。コネクタを使用するすべての人は、ログイン UI でこの文字列を貼り付ける必要があります。

openssl rand -hex 32

出力を保存してください — これをシークレットとして設定し、ChatGPT/Claude で使用します。

3. Google Cloud（OAuth クライアント）の設定

docs/SETUP_GCP.md のステップバイステップに従ってください。承認済みのリダイレクト URI には手順1で取得した Worker URL を使用します。最終的に Client ID と Client Secret が発行されます。

これが最も長い手順です（初回は約10分）が、一度だけ行えば OK です。

4. Worker シークレットの設定

npx wrangler secret put MCP_BEARER_TOKEN
# paste the value from step 2

npx wrangler secret put GOOGLE_OAUTH_CLIENT_ID
# paste the Client ID from step 3

npx wrangler secret put GOOGLE_OAUTH_CLIENT_SECRET
# paste the Client Secret from step 3

または Cloudflare ダッシュボードから: Workers & Pages → 該当 worker → Settings → Variables and Secrets → それぞれを Secret タイプで追加してください。

ヒント — Windows でのエンコーディングの落とし穴: ファイルの内容をパイプで渡す場合（例: Get-Content | wrangler secret put）、そのファイルに UTF-8 BOM が付いていると、BOM もシークレットに含まれて JSON 解析が壊れます。Cloudflare ダッシュボードや対話型の wrangler secret put（プロンプトに貼り付け）を使えば、この問題を完全に回避できます。

5. ChatGPT に接続（Plus/Pro/Team）

ChatGPT → Settings → Connectors → Add custom connector:

• Name: gsc

• MCP Server URL: https://YOUR-WORKER-URL/mcp（末尾は /mcp である必要があります）

• Authentication: OAuth

• 「I understand and want to continue」にチェック

• Create

ポップアップが開き、Worker のログイン UI に移動します。MCP_BEARER_TOKEN を貼り付け → Continue with Google → → Google がログインを求めます（GSC プロパティを所有するアカウントでログイン）→ webmasters.readonly を許可 → ChatGPT にリダイレクトされ、コネクタが有効になります。

新しいチャットで、ツールバーから gsc コネクタを有効化し、「List my Google Search Console sites」と尋ねてください。プロパティが表示されるはずです。

6. （任意）Claude.ai に接続（Pro/Team）

Settings → Integrations → Add custom integration → 同じ URL、同じフローです。

ローカル開発

git clone https://github.com/JuJu78/gsc-mcp-connector
cd gsc-mcp-connector
npm install
cp .dev.vars.example .dev.vars
# edit .dev.vars with your real Client ID + Client Secret + bearer token
npx wrangler dev

開発サーバーは http://localhost:8787 で動作します。ローカル開発では Google OAuth フローを完全に完了できないことに注意してください。Google のリダイレクト URI は HTTPS を必要とするためです。真のエンドツーエンドテストを行うには、Cloudflare にデプロイし、workers.dev の URL に対してテストしてください。

制限事項

• 読み取り専用。書き込み操作（サイトマップ送信、インデックス登録リクエストなど）は意図的に除外しています。LLM のコンテキストではリスクが伴うためです。必要であれば PR を送ってください。

• シングルテナント仕様。一人の運用者ガデプロイし、一つのBearer トークンがコネクタをガードし、アクセスは Google OAuth フローを完了したユーザーに紐づけられま。マルチユーザー SaaS 型は対象外です。

• OAuth 同意画面が "Testing" モードの場、100 テスユーザーまでの制限がありま（個人/チーム利用には十分以大）。よ広く配布すには、アプリを Google の審査（webmasters.readonly は「感度な」射程で、手動レビューが必要）に提出する必要がありま。

• GSC API クォータ — プロジェクトあたり1200クエリ/分、30000/日。インタラクティブな利用には十分です。

• 日付範囲 — GSC は過去16か月間のデータを返します。それ以前の日付はエラーになります。

トラブルシューティング

技術スタック

• Cloudlfare Workers + Durable Objects（agents SDK ≥0.12 経由）

• @cloudflare/workers-oauth-provider で OAuth 2.1 + DCR + PKCE

• @modelcontextprotocol/sdk でツール定義

• K V ネームスペース OAuth_KV で OAuth 状態を管理

• Google OAuth 2.0 フローを Web Cryptto API（Node 依存なし）でネイティブに署名

クレジット

Julien Gourdon によって制作 — 検索と AI の交差点を探求する SEO コンサルタント。

ライセンス

MIT — LICENSE を参照。