GA4 SEO MCP

English · Español

ga4-seo-mcp — AI エージェント向けのサイト計測を一貫して実現

サイト計測を一貫して準備します。GA4 ＋ Search Console ＋ PageSpeed を組み合わせ、必要に応じて安全対策を施した書き込みも行えます。 Google Analytics 4 と Search Console 向けのオープンソースのModel Context Protocolサーバーです。Google 向けの MCP サーバーの多くはデータを 読み取る だけですが、このサーバーではセットアップも行えます。プロパティ、ウェブストリーム、キーイベント、カスタムディメンション、Search Console の DNS 検証、サイトマップ、PageSpeed のベースラインを設定できます。指定があるまでは読み取り専用です。

タグ： mcp-server · ga4 · google-analytics · search-console · seo · pagespeed · core-web-vitals · keyword-research · claude-code · cursor

_{実際の実行例：公開サイトに対する psi_audit と、新しいサイトのセットアップを計画する bootstrap_site_measurement(apply=False) です。デモスクリプトではアカウント ID が伏せられます。}

---

💡 なぜこれを選ぶのか？

サイトを公開するたびに、同じ作業が必要になります。GA4 プロパティとウェブストリームを作成し、キーイベントを指定し、カスタムディメンションを登録し、Search Console にドメインを追加し、DNS TXT レコードを公開して検証し、サイトマップを送信し、PageSpeed のベースラインを記録します。ga4-seo-mcp を使えば、これらの作業をエージェントが提示する 1 つのプランと、1 回の確認にまとめられます。

	ga4-seo-mcp	Google 公式 GA4 MCP	search-console-mcp	google-seo-mcp
GA4 レポート（Data API）	✅	✅	✅	✅
Search Console	✅	—	✅（＋ Bing）	✅
PageSpeed Insights / CrUX	✅	—	✅	✅
GA4 プロパティ ＋ ウェブストリームの作成	✅	—	—	—
キーイベント / カスタムディメンションの作成	✅	—	—	✅
Search Console の DNS 検証	✅	—	—	—
1 回の呼び出しでサイトのプランを作成 → 適用（冪等）	✅ bootstrap_site_measurement	—	—	—
デフォルトで読み取り専用	✅ 書き込みツールは登録すらされません	読み取り専用のみ	ドキュメントを参照	✅ 読み取り専用モード
ツールセット	✅	—	—	✅
言語	Python	Python	TypeScript	TypeScript

_{各プロジェクトの README に基づく情報（2026-10-19 時点）です。「—」は、ドキュメントで確認できなかったことを示します。修正のご指摘を歓迎します。各プロジェクトは Bing、AdSense、WordPress、GEO 監査など、本プロジェクトより幅広い機能を提供します。一方、本プロジェクトは計測のセットアップにより深く取り組んでいます。}

🤝 代わりに対応してほしい方へ

このサーバーは Germani Uicab が構築・保守しています。ご自身での実行を希望されない場合は、ServerStack Solutions が GA4 と Search Console の計測設定を整えます。書面での計画、プロパティとキーイベントの設定、DNS 検証とサイトマップの設定、PageSpeed のベースライン測定を行い、引き渡し前に QA も実施します。

---

追加機能：オプションのキーワード調査には DataForSEO（ロングテールキーワードの正確な検索ボリューム）と Google Ads Keyword Planner（無料、区分ごとの検索ボリューム）を利用できます。デフォルトは es-MX ですが、変更できます。

---

⚡ クイックスタート

1. uv 0.13.4 以降をインストールします — クライアントは uvx を使ってサーバーを起動するため、ほかにインストールするものはありません。

2. 必要最小限のスコープでログインします。 CLI は、有効にしたツールセットに応じて、正確な gcloud コマンドを表示します。

uvx ga4-seo-mcp auth-command --client-id-file=oauth-client.json
# gcloud auth application-default login --client-id-file=oauth-client.json --scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/webmasters.readonly

表示されたコマンドを実行してください。Google は gcloud に組み込まれた OAuth クライアントで Analytics と Search Console のスコープをブロックするため、独自のクライアント（初回のみ数分で設定できます）またはサービスアカウントが必要です。どちらの方法も docs/AUTH.md で説明しています。

3. クライアントに接続する前に、すべて確認します（読み取り専用で、変更は行いません）。

uvx ga4-seo-mcp doctor
# [ok] credentials found: Credentials via Application Default Credentials
# [ok] access token refreshed
# [ok] token has the 2 scope(s) these toolsets need
# [ok] admin: <n> account(s) visible on the first page
# [ok] data: responded (<n> metrics in the schema)
# [ok] gsc: <n> site(s) visible
# [ok] psi: no Google login needed; PAGESPEED_API_KEY set
# all checks passed

4. クライアントに追加します（Claude Code の例。他のクライアントについては以下をご覧ください）。

claude mcp add ga4-seo -- uvx ga4-seo-mcp

次のように尋ねてください：「GA4 プロパティの一覧を表示して、最初のプロパティについて先週のセッション数を教えてください。」

---

🧰 ツールセット、スコープ、ツール

--toolsets（または GA4SEO_TOOLSETS）を使って、必要なものだけを有効にします。デフォルトは admin,data,gsc,psi です。有効なツールセットのツールのみが登録され、OAuth スコープもそれに応じて設定されます。

ツールセット	内容	スコープ（読み取り専用）	--enable-writes による追加スコープ	ツール（読み取り＋書き込み）
admin	GA4 Admin API：アカウント、プロパティ、ストリーム、キーイベント、カスタムディメンション、Ads リンク、bootstrap_site_measurement	analytics.readonly	analytics.edit	9 + 10
data	GA4 Data API：レポート、リアルタイム、上位ページ、イベント、トラフィックソース、ポートフォリオ	analytics.readonly	—	8 + 0
gsc	Search Console：クエリ、ページ、サイトマップ、ドメインの追加＋DNS 検証	webmasters.readonly	webmasters, siteverification	5 + 3
psi	PageSpeed Insights：Lighthouse のラボデータ＋CrUX のフィールドデータ	なし（PAGESPEED_API_KEY を推奨）	—	2 + 0
dataforseo	DataForSEO のキーワード候補と正確な検索ボリューム（有料）	なし（DATAFORSEO_LOGIN / DATAFORSEO_PASSWORD）	—	2 + 0
ads	Google Ads Keyword Planner（pip install 'ga4-seo-mcp[ads]' が必要）	adwords	—	2 + 0

実際のレジストリに基づくツール数は、デフォルトで 24、--enable-writes を指定すると 37、--toolsets data を指定すると 8、すべてのツールセットと書き込みを有効にすると 41 です。説明付きの全一覧は docs/TOOLS.md にあります（レジストリから生成され、CI でチェックされています）。

プロンプト： audit_ga4_setup、seo_360_audit、portfolio_performance_digest、launch_site_measurement（ガイド付きフロー：計画 → 確認 → 適用 → DNS 検証 → サイトマップ → PageSpeed のベースライン測定）。

bootstrap_site_measurement

bootstrap_site_measurement(site_url="https://example.com", account_id="123456789",
                           property_display_name="Example", time_zone="America/Mexico_City",
                           currency_code="USD", key_events=["generate_lead"],
                           custom_dimensions=[{"parameter_name": "plan_type", "display_name": "Plan type"}])

• apply=False（デフォルト）：計画を返します。 読み取り専用で、常に登録されています。サイトのドメインから既存のプロパティとウェブストリーム、すでに宣言されているキーイベントとカスタムディメンション、Search Console のドメインプロパティを探し、作成される項目を一覧表示します。
• apply=True：計画を実行します。 サーバーが --enable-writes を指定して実行されている場合にのみ動作します。そうでない場合は、何も変更する前に失敗します。冪等性があり、すでに存在する項目はスキップするため、再実行できます。測定 ID（G-…）と DNS TXT トークンを含む、手順ごとのレポートを返します。
• DNS 検証（sc_verify_site_dns）とサイトマップ（sc_submit_sitemap）は、引き続き明示的な後続手順です。最初に TXT レコードを公開する必要があります。

---

🔒 セキュリティモデル

デフォルト設定は、ノートパソコンを使う単一ユーザー向けに安全です。詳細と脅威モデルについては、SECURITY.mdを参照してください。

• デフォルトでは読み取り専用です。 --enable-writes（または GA4SEO_ENABLE_WRITES=1）を指定しない場合、作成、更新、削除、送信、検証を行うツールは一切登録されません。モデルは、存在しないものを呼び出せません。
• すべてのツールに MCP アノテーションがあります。 読み取りには readOnlyHint、削除と更新には destructiveHint、繰り返しても問題ない場合には idempotentHint、すべてのツールには openWorldHint が設定されます。これらを考慮するクライアントは、読み取りを自動承認し、書き込みの前に確認を求めることができます。
• 最小限のスコープ： 各 Google クライアントは、実行する呼び出しに必要なスコープのみを要求します。auth-command は、使用するツールセットに必要なスコープのみを要求します。
• HTTP トランスポート（--transport streamable-http）：127.0.0.1 にバインドし、DNS リバインディング対策を有効にし、MCP_CORS_ORIGINS が設定されていない場合は CORS を無効にします。また、任意のベアラートークン MCP_AUTH_TOKEN を設定できます（トークンがない場合は 401）。トークンなしで 0.0.0.0 をリッスンすると警告が表示されます。また、LAN クライアントには MCP_ALLOWED_HOSTS が必要です。設定されていない場合、リバインディング対策により 421 が返されます。
• シークレット（DataForSEO、Ads デベロッパートークン、PageSpeed キー）は、環境変数または chmod 600 を設定したファイルからのみ取得され、ログへの記録やエラーでの返却は行われません。

---

⚙️ 設定

変数	デフォルト	説明
GOOGLE_APPLICATION_CREDENTIALS	—	サービスアカウントのキーファイルです。未設定の場合は、gcloud の Application Default Credentials が使用されます。
GA4SEO_TOOLSETS	admin,data,gsc,psi	--toolsets と同じです。
GA4SEO_ENABLE_WRITES	0	1 を設定すると、--enable-writes と同じになります。
PAGESPEED_API_KEY	—	推奨：匿名での PageSpeed クォータは共有されており、上限に達していることがよくあります（429）。
DATAFORSEO_LOGIN, DATAFORSEO_PASSWORD	—	dataforseo ツールセットで使用します。
GOOGLE_ADS_DEVELOPER_TOKEN	—	ads ツールセットで使用します。または、~/.config/ga4-seo-mcp/dev-token に chmod 600 を設定して保存します。
GOOGLE_ADS_LOGIN_CUSTOMER_ID	—	マネージャー（MCC）アカウントを介して操作する場合のみ必要です。
MCP_TRANSPORT	stdio	stdio、streamable-http、または sse です。
MCP_HOST / MCP_PORT	127.0.0.1 / 8000	HTTP のバインドアドレスとポートです。ループバック以外の特定のアドレスは、許可される Host ヘッダーに追加されます。0.0.0.0 は追加されないため、LAN クライアントには MCP_ALLOWED_HOSTS を設定してください。
MCP_AUTH_TOKEN	—	すべての HTTP リクエストで Authorization: Bearer <token> を必須にします。
MCP_CORS_ORIGINS	—	ブラウザクライアント向けの、カンマ区切りの完全一致オリジンです。* は指定しないでください。
MCP_ALLOWED_HOSTS	—	クライアントが使用するホスト/IP 値（例：192.168.1.10）をカンマ区切りで指定します。0.0.0.0 にバインドして LAN 経由で接続する場合は必須です。DNS リバインディング対策により、それ以外はすべて拒否され、421 が返されます。

.env.exampleを出発点としてコピーしてください。

---

🔌 クライアントを接続する

すべてのクライアントは stdio 経由でサーバーを起動します。サイトを実際にセットアップするセッションでのみ、args に --enable-writes を追加してください。

Claude Code

claude mcp add ga4-seo -- uvx ga4-seo-mcp
# with options:
claude mcp add ga4-seo -e PAGESPEED_API_KEY=your-key -- uvx ga4-seo-mcp --toolsets admin,data,gsc,psi

Claude Desktop（claude_desktop_config.json）および Cursor（~/.cursor/mcp.json）

{
  "mcpServers": {
    "ga4-seo": {
      "command": "uvx",
      "args": ["ga4-seo-mcp"],
      "env": { "PAGESPEED_API_KEY": "your-key" }
    }
  }
}

VS Code（.vscode/mcp.json）

{
  "servers": {
    "ga4-seo": {
      "type": "stdio",
      "command": "uvx",
      "args": ["ga4-seo-mcp"]
    }
  }
}

Docker（stdio）。認証情報ファイル（gcloud の ADC ファイルまたはサービスアカウントキー）を読み取り専用でマウントし、コンテナが 0600 ファイルを読み取れるように、自分のユーザーとして実行してください。

docker run -i --rm --user "$(id -u):$(id -g)" \
  -v ~/.config/gcloud/application_default_credentials.json:/creds/credentials.json:ro \
  -e GOOGLE_APPLICATION_CREDENTIALS=/creds/credentials.json \
  ghcr.io/germaniu/ga4-seo-mcp

HTTP（複数のクライアントで 1 つのサーバーを共有する場合）：

MCP_AUTH_TOKEN=$(openssl rand -hex 32) uvx ga4-seo-mcp --transport streamable-http
# endpoint: http://127.0.0.1:8000/mcp  (send Authorization: Bearer <token>)

---

🩹 トラブルシューティング

症状	原因と対処法
gcloud ... login 中に This app is blocked／access_denied が表示される	gcloud 組み込みのクライアントでは、Analytics または Search Console のスコープをリクエストできません。独自の OAuth クライアント（--client-id-file）を使用し、その同意画面に自分を テストユーザー として追加してください — docs/AUTH.md。
cloud-platform scope is required but not requested	ga4-seo-mcp auth-command が出力するコマンドを使用してください。gcloud のスコープ一覧には cloud-platform が必要です。サーバー自体はこれをリクエストしません。
403 ... API has not been used in project	割り当てプロジェクトで Google Analytics Admin API、Google Analytics Data API、Search Console API を有効にしてから、gcloud auth application-default set-quota-project my-gcp-project を実行してください。
403 ... does not have sufficient permissions for this property	GA4 プロパティまたは Search Console サイトに、自分のユーザー（またはサービスアカウントのメールアドレス）を追加してください。
ga4-seo-mcp doctor でトークンのスコープ不足が表示される	ツールセットまたは書き込みを有効にする前にログインしています。auth-command の出力を再実行してください。
書き込みツールが表示されない	--enable-writes を付けてサーバーを起動してください。意図的にデフォルトでは無効になっています。
PageSpeed Insights error 429	匿名ユーザー向けの割り当ては全員で共有されています。API キーを作成し、PAGESPEED_API_KEY を設定してください。
Keyword Planner のボリュームが丸められている（10、30、170、210…）	アクティブな広告費がないアカウントでは、Google Ads はボリュームを 区分化 して報告します。正確な数値には dataforseo ツールセットを使用してください。
削除した GA4 プロパティがまだ表示される	delete_property は論理削除です。Google は 35 日間 ゴミ箱に保持します（list_properties(include_deleted=True)）。
HTTP が 421 Invalid Host header を返す	DNS リバインディング保護が原因です。バインドしたホスト（127.0.0.1／localhost、または MCP_HOST のアドレス）で接続してください。
HTTP が 401 を返す	Authorization: Bearer $MCP_AUTH_TOKEN を送信してください。

---

📚 ドキュメント

• docs/AUTH.md — 独自の OAuth クライアントとサービスアカウントの違い、ツールセットごとのスコープ、テストユーザー。
• docs/TOOLS.md — レジストリから生成された、すべてのツールとプロンプト。
• docs/ARCHITECTURE.md — モジュール、登録、セキュリティレイヤー。
• SECURITY.md · CONTRIBUTING.md · CHANGELOG.md

🧪 開発

uv sync --all-extras
uv run ruff check . && uv run ruff format --check . && uv run pytest
uv run python scripts/smoke_stdio.py --expect 24   # real stdio initialize + tools/list

📄 ライセンス

MIT。Google との提携や、Google による推奨を受けているものではありません。Google Analytics、Search Console、PageSpeed Insights は Google LLC の商標です。