Google Analytics 4 MCP

Google Analytics 4 MCP

Google Analytics 4 用の読み取り専用 MCP サーバーです。17 個のツールで、Data API と Admin API の読み取り機能を網羅します。標準、バッチ、ピボット、リアルタイム、ファネルのレポート、メタデータカタログと互換性チェック、プロパティ、ストリーム、カスタムディメンションと指標、キーイベント、オーディエンス、Google Ads リンク、アノテーション、アクセスレポートの管理リストを利用できます。このサーバーは、すべての分析クライアント向けに本番環境で運用しています。

インストール

Claude Code：

claude mcp add ga4 -e GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json -- uvx scalably-ga4-mcp

Codex：

codex mcp add ga4 --env GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json -- uvx scalably-ga4-mcp

Claude Desktop：最新の GitHub リリースから ga4-mcp.mcpb をダウンロードして開きます。

セットアップ

1. Google Cloud でプロジェクトを作成するか選択し、そのプロジェクトで Google Analytics Data API と Google Analytics Admin API を有効にします（「API とサービス」→「ライブラリ」）。
2. そのプロジェクトでサービスアカウントを作成し、JSON キーをダウンロードします。
3. クエリする各 GA4 プロパティで、サービスアカウントのメールアドレスに閲覧者の権限を付与します（「管理」→「プロパティのアクセス管理」）。

OAuth 同意画面は不要です。サーバーは analytics.readonly スコープを使ってサービスアカウントとして認証します。サービスアカウントはアクセス権が付与されたプロパティをすべて読み取れるため、上記の手順 3 以外にクライアントごとの設定はありません。

最初に ga4_list_account_summaries を呼び出して、サービスアカウントが参照できる property_id の値を確認し、そのうち 1 つをレポートまたは管理ツールに渡します。

ツール（17）

ツール	機能
ga4_list_account_summaries	このサービスアカウントがアクセスできるすべての GA4 アカウントと、その配下のプロパティを一覧表示します
ga4_get_property_details	単一の GA4 プロパティの全メタデータを取得します
ga4_list_data_streams	GA4 プロパティ上のすべてのデータストリーム（ウェブ、iOS、Android）を一覧表示します
ga4_list_custom_dimensions	GA4 プロパティに設定されたカスタムディメンションを一覧表示します
ga4_list_custom_metrics	GA4 プロパティに設定されたカスタム指標を一覧表示します
ga4_list_key_events	GA4 プロパティのキーイベント（旧コンバージョン）を一覧表示します
ga4_list_audiences	GA4 プロパティに定義されたオーディエンスを一覧表示します
ga4_list_google_ads_links	GA4 プロパティにリンクされた Google Ads アカウントを一覧表示します
ga4_list_property_annotations	GA4 プロパティのレポート用アノテーションを一覧表示します
ga4_run_access_report	過去 12 か月間に GA4 プロパティで誰が何を読み取ったかを示す監査ログです
ga4_get_metadata	プロパティの GA4 ディメンションと指標のカタログ全体を取得します
ga4_run_report	GA4 の標準レポートを実行する、主要なツールです
ga4_batch_run_reports	1 回のリクエストで最大 5 件の GA4 レポートを実行します
ga4_run_pivot_report	GA4 のピボットレポートを実行します
ga4_run_realtime_report	過去 30 分間を対象にした GA4 のリアルタイムレポートを実行します
ga4_check_compatibility	ディメンションと指標の組み合わせを一緒にクエリできるか検証します
ga4_run_funnel_report	GA4 のファネルレポートを実行します（v1alpha、離脱分析）

設定

変数	必須	用途
GOOGLE_APPLICATION_CREDENTIALS	はい	analytics.readonly スコープを持つ Google サービスアカウント JSON ファイルのパス。各プロパティをサービスアカウントのメールアドレスと共有します
GA4_LOG_LEVEL	いいえ	INFO（デフォルト）または DEBUG

フィルター式の形式

dimension_filter / metric_filter を受け取る各ツールには、次の形式の dict を渡します。

{"filter": {"field_name": "country", "string_filter": {"value": "US"}}}

ブール値グループを使って組み合わせます。

{"and_group": {"expressions": [
  {"filter": {"field_name": "country", "string_filter": {"value": "US"}}},
  {"filter": {"field_name": "deviceCategory", "string_filter": {"value": "mobile"}}}
]}}

{"field_name": ..., "string_filter": ...} の形式の値は、自動的に {"filter": {...}} でラップされます。

返信の形式

各ツールは、status（succeeded、partial、no_op）、operation、summary、target、result、proof、warnings、recovery を含む JSON を返します。失敗時は、テキストが ga4_request_failed: <message> <hint> のツールエラーが返されます。partial ステータスでの proof.nextOffset は、そのオフセットから続行することを意味します。proof.propertyQuota にはプロパティの Data API 残りクォータが含まれるため、呼び出し側でリクエスト頻度を調整できます。レスポンスがサンプリング済み、しきい値適用済み、またはカーディナリティの高い行が (other) にまとめられている場合、proof.dataQualityLimited は true です。このような結果は正確な値ではなく、おおよその傾向を示すものとして扱ってください。

制限事項

Data API のレスポンスは最大 250,000 行です（サーバーは、クライアントが指定した上限がこれを超える場合、上限を引き下げます）。バッチレポートは 1 回の呼び出しにつき最大 5 件です。ファネルレポートは最大 10 ステップです。リアルタイムレポートでは、直近 30 分間のみを対象とする、より小規模な別のディメンションと指標のカタログを使用します。リアルタイム以外のデータは、通常 24〜48 時間遅れて反映されます。ファネルレポートは v1alpha であり、その形式は上流で変更される可能性があります。各クォータ枠（コアレポート、リアルタイム、ファネル）では、プロジェクトごと、プロパティごとに 1 時間あたり約 14,000 クォータトークンが許可されます（複雑なクエリでは、1 トークンを超えて消費する場合があります）。360 プロパティには 10 倍の倍率が適用されます。正確な数値に依存する前に、Google の最新のクォータページを再確認してください。

検証

各リリースでは、パッケージのバージョン、.mcpb の sha256、そしてそのパッケージのビルド元となった本番環境のコミットを CHANGELOG.md に記載しています。CI では、プッシュのたびにテストと、ビルドした wheel のクリーンインストールを実行します。

プライバシーポリシー

このサーバーは、ユーザー自身の認証情報を使用して、ユーザーのマシン上でローカルに実行されます。個人データを収集せず、テレメトリーを含まず、データを永続的に保存せず、ラップ対象のベンダー API とのみ通信します。Scalably を含む第三者にユーザーのデータが送信されることはありません。お問い合わせ先：[email protected]。正式版：https://scalably.io/connector-privacy.html

ライセンス

MIT。Copyright Scalably。