Google Analytics 4

この動画では、サンプルデータを使ったホスト版 getmcpads を紹介しています。クリエイティブギャラリーやアラートから、Google Sheets へのエクスポートや一括配信まで、MCP Apps はホスト版製品の機能です。このリポジトリでは、単体で使えるネイティブ API ツールを提供しています。

読み取りツール 27 個 · 読み取り専用として設計されています。

stdio MCP に対応する Claude Desktop、Claude Code、Cursor などのクライアントと、ご自身のプラットフォーム認証情報を使ってローカルで実行できます。リクエストはプラットフォームに直接送信されます。ChatGPT の対応構成を含む、管理された接続を利用する場合は、ホスト版をご利用ください。

新着情報

v2.1.1：Zod 4 セキュリティアップデート · 2026 年 10 月 26 日

• zod を 4.6.7 に更新しました。4.6.6 より前のすべての Zod リリースは、重大度の高いアドバイザリ GHSA-mrhx-c7xc-m3w5 の対象です。サイズ制約付きコレクションのサイズが大きすぎる場合に検証処理でメモリを使い果たす可能性があり、修正を含む Zod 3 のリリースはありません。npm audit --omit=dev で、再び脆弱性が報告されなくなりました。
• Zod 3 の検証動作を維持しています。パラメーターのデフォルト値は使用前に検証・補完されるため、省略されたオブジェクトにも引き続き必須フィールドを指定する必要があります。
• パラメーターが省略可能、またはデフォルト値を持つ場合も、各パラメーター固有の説明を維持しています。Zod 4 ではラップされたスキーマにのみ説明が保存されるため、そうしないと共通のフォールバック説明で置き換えられる可能性があります。
• MCP 経由で公開されるツール名、パラメーター、説明に変更はありません。server-card.json は Zod 4 の JSON Schema 出力で再生成されており、一部の制約の表記が異なります。

以前のリリース

バージョン	日付	主な内容
2.1.0	2026 年 10 月 23 日	プロパティの許可リストと失効したトークンの処理
2.0.1	2026 年 9 月 23 日	公開リポジトリを復旧
2.0.0	2026 年 9 月 20 日	ゲートウェイとの同期とセキュリティ修正
1.1.0	2026 年 9 月 13 日	プラットフォーム機能の同期と品質要件
1.0.2	2026 年 8 月 30 日	MCP 経由でパッケージバージョンを通知
1.0.1	2026 年 8 月 30 日	server.json と mcpName を追加し、公式 MCP Registry に com.getmcpads/google-analytics として登録
1.0.0	2026 年 8 月 29 日	最初のオープンソースリリース

変更履歴の全文 · すべてのリリース

ソースの同期については、SOURCE_SYNC.md をご覧ください。

アップグレードに関する注意事項

Node.js 22.23.4、24.22.1、26.12.1、またはこれらの系列のより新しいリリースが必要です。古いリリースには2026年10月のセキュリティ修正が含まれていません。また、そのいずれかでサーバーを起動すると、stderr に警告が出力されます。CI では Node 22、24、26 を対象としています。

このリリースでは、設定に破壊的変更はありません。3.0.0 で予定している変更をお知らせします。GA4_PROPERTY_IDS は 2.x では任意ですが、3.0.0 では必須になります。設定されている場合、すべてのツールで使用できるプロパティは一覧にあるものに制限され、GA4_PROPERTY_ID はそのいずれかである必要があります。設定されていない場合、サーバーはこれまでどおり起動し、stderr に設定を推奨するメッセージを1行出力します。ツールとそのスキーマに変更はありません。

このリリースをインストールする

これは GitHub のソースリリースです。npm と MCP Registry のバージョンは別途公開されています。以下のコマンドでは、この特定のバージョンを指定します。このドキュメント後半にあるバージョンを固定していない npx の例では、現在 npm で入手できるバージョンが選択されます。

git clone --branch v2.1.1 --depth 1 https://github.com/get-mcp-ads/google-analytics-mcp-server.git
cd google-analytics-mcp-server
npm ci
npm run build

MCP クライアントで、node を絶対パス指定の dist/cli.js および以下に記載するプラットフォーム認証情報とともに実行するよう設定してください。

マネージド接続をご希望ですか？ ホスト型 getmcpads で Google Analytics 4 を使用する。アカウントを接続し、アシスタントがアクセスできるデータを選択して、ホスト型 MCP 接続を使用します。最新の機能とプランについては、サイトをご確認ください。

利用できる機能

27 個の読み取りツール	レポート、ピボット、ファネル、リアルタイムのほか、Admin API：プロパティ、データストリーム、カスタム定義、キーイベント、オーディエンス
診断	E コマース、BigQuery エクスポート、サーバーサイドタグ設定、オーディエンスのエクスポート、クォータのスナップショット
51 個の指標、62 個のディメンション	互換性マトリックスにより、無効な組み合わせを API に送信する前に検出します
6 個のリソース	モデルが読み取れる最新のカタログ：指標、ディメンション、互換性ルール、12 個のワークフローレシピ
識別子のマスキング	アクセスバインディングとオーディエンスのエクスポートでは、ユーザー、メールアドレス、デバイスの識別子がデフォルトでマスキングされます。明示的にオプトインすると表示できます
書き込み機能は一切ありません	フラグで制御しているのではなく、コードそのものの仕様です。詳しくは以下をご覧ください

呼び出し前に確認する互換性

GA4 では多くの指標とディメンションの組み合わせが拒否されますが、どの組み合わせに問題があるのかをエラーから特定できることはほとんどありません。このサーバーには互換性マトリックスが含まれているため、ga4_check_compatibility と ga4_validate_query を使えば、呼び出しやクォータトークンを消費する前に組み合わせを確認できます。

ここでは、広告プラットフォームの場合よりもクォータが重要です。GA4 ではプロパティごとに1日あたりのトークンが消費され、不用意な探索的クエリをいくつか実行しただけで使い切ることがあります。ga4_get_property_quotas_snapshot で残量を確認できます。

---

読み取り専用である理由と、その方針を維持する理由

書き込みツールはなく、追加する環境変数もありません。すべてのツールは Data API または Admin API の読み取りメソッドを呼び出します。

これは、単に慎重を期しているというだけではありません。レポートの読み違いなら、誤った回答として気づくことができます。一方で、分析プロパティへの誤った書き込み、オーディエンスの削除、データストリームの編集は、ほかのすべてを評価する基準となる記録を破損させ、しかも多くの場合、それに気づけません。公開しているほかのサーバーには、必須のプレビューで保護された書き込みツールがあります。このサーバーにはありません。

書き込みを保護付きで提供する広告プラットフォームのサーバー： Meta Ads · Google Ads · TikTok Ads

---

個人データ

分析データは、デフォルトでは匿名ではありません。GA4 プロパティには、自分で設定した userId、デバイス識別子、または Google Signals の仮名 ID が含まれる場合があります。MCP の会話では、ツールが返すものはすべてモデルに送信されます。

このサーバーが返す可能性のある識別子は、デフォルトですべてマスキングされます。識別子の表示は明示的なオプトインが必要であり、デフォルトでは表示されません。

ツール	動作
ga4_list_admin_resources	アクセスバインディングに含まれるユーザー識別子とメール識別子をマスキングします
ga4_query_audience_export	識別子列を、エクスポート独自のディメンションメタデータと照合してマスキングします
ga4_get_audience_export_diagnostics	行サンプルにも同じマスキングを適用します

これらのツールはいずれも includePersonalIdentifiers: true を指定すると生の値を返します。デフォルトは false です。

オーディエンスエクスポートの行は位置ベースのため、マスキングではエクスポートのディメンションメタデータを読み取り、識別子列を特定します。そのメタデータがない場合、安全な列を推測するのではなく、行のすべての値をマスキングします。安全側に倒して処理を失敗させることが目的です。

レポート行はマスキングされません。 ga4_run_report やその他のレポートツールは、要求した内容を返します。レポートが返す数値を変更するより、そのまま返すほうが適切です。

したがって、判断は一つだけです。プロパティに個人情報と見なす userId が含まれている場合、トランスクリプトが自分のマシンの外部に送信される会話では、それをレポートのディメンションとして要求しないでください。

---

認証情報の取得

一度だけ取得する3つの値です。

1. OAuth クライアント

Google Cloud プロジェクトで、Google Analytics Data API と Google Analytics Admin API を有効にしてから、APIs & Services → Credentials で OAuth クライアントを作成します。ローカルで使用する場合は Desktop app を選択します。client ID と client secret を控えてください。

2. リフレッシュトークン

GA4 プロパティへのアクセス権がある Google アカウントでログインし、OAuth 同意フローを一度実行して、リフレッシュトークンを保管してください。analytics.readonly スコープで十分であり、付与するのはこのスコープだけにしてください。

📖 インストール型アプリ向け Google OAuth

リフレッシュトークンは期限切れになりません。 これは機密性の高い値です。これを持つ人は誰でも、無期限にアクセストークンを発行できます。このサーバー専用の OAuth クライアントを使用すれば、そのクライアントだけを個別に取り消せます。

3. プロパティ ID（任意）

毎回渡す手間を省くには、GA4_PROPERTY_ID を設定します。GA4 の Admin → Property Settings で確認するか、ga4_list_properties で一覧表示できます。

最初の呼び出しでは ga4_health_check を実行してください。認証情報を検証し、秘密情報を表示せずに、実際にアクセス可能なプロパティを一覧表示します。

---

セットアップ

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS） または %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "google-analytics": {
      "command": "npx",
      "args": ["-y", "@getmcpads/google-analytics-mcp-server"],
      "env": {
        "GA4_CLIENT_ID": "your-client-id",
        "GA4_CLIENT_SECRET": "your-client-secret",
        "GA4_REFRESH_TOKEN": "your-refresh-token",
        "GA4_PROPERTY_IDS": "123456789"
      }
    }
  }
}

Claude Desktop を再起動します。「Google Analytics のプロパティを一覧表示して」と尋ねてください。

Claude Code

claude mcp add google-analytics --env GA4_CLIENT_ID=... --env GA4_CLIENT_SECRET=... --env GA4_REFRESH_TOKEN=... -- npx -y @getmcpads/google-analytics-mcp-server

Cursor

プロジェクト内の .cursor/mcp.json に、上記の Claude Desktop 設定と同じ形式で記述します。

ソースから実行

git clone https://github.com/get-mcp-ads/google-analytics-mcp-server.git
cd google-analytics-mcp-server
npm install && npm run build
cp .env.example .env   # then fill in your credentials
npm start

設定

変数	デフォルト	説明
GA4_CLIENT_ID	なし	必須。 OAuth クライアント ID
GA4_CLIENT_SECRET	なし	必須。 OAuth クライアントシークレット
GA4_REFRESH_TOKEN	なし	必須。 同意フローで取得
GA4_PROPERTY_ID	なし	任意のデフォルト値。毎回渡す手間を省きます
GA4_PROPERTY_IDS	未設定	推奨。すべてのツールで利用できるプロパティ ID をカンマ区切りで指定します。未設定の場合、認証情報でアクセスできるすべてのプロパティを利用できます。3.0.0 では必須
LOG_LEVEL	info	debug、info、warn、error

セットアップはいつでも次の方法で確認できます。

npm run doctor

---

ツール

以下にすべてのツールを記載します。パラメーターと出力の完全なスキーマについては、server-card.json を参照してください。

27 個の読み取りツール

| ツール | 目的 | | --- | --- | | `ga4_health_check` | 読み取り専用の GA4 ヘルスチェックです。 | | `ga4_list_properties` | 現在の認証情報でアクセス可能なすべての GA4 プロパティを一覧表示します。 | | `ga4_run_report` | インテリジェントなクエリ計画で GA4 アナリティクスレポートを実行します。 | | `ga4_run_realtime_report` | 読み取り専用の GA4 Data API リアルタイムレポートを実行します。 | | `ga4_get_metadata` | 特定の GA4 プロパティで利用可能なディメンションと指標の完全な一覧を取得します。 | | `ga4_get_custom_definitions` | GA4 Data API メタデータで公開されるカスタムディメンションとカスタム指標を一覧表示します。 | | `ga4_get_key_events` | メタデータを考慮した Data API レポートを使用して、GA4 のキーイベント／コンバージョンを一覧表示します。 | | `ga4_get_ecommerce_diagnostics` | 指定した期間について、主要な e コマースイベント、収益指標、商品単位のレポートを対象とする読み取り専用の e コマース診断を実行します。 | | `ga4_get_event_parameters` | GA4 メタデータとイベントレポートから、可能な範囲でイベントパラメーターを一覧表示します。 | | `ga4_run_funnel_recipe` | イベント名／ページパスの各ステップについて GA4 レポートを 1 つずつ使用する、読み取り専用で設定可能なファネルレシピを実行し、簡単なステップ数を返します。 | | `ga4_get_audience_export_diagnostics` | 読み取り専用のオーディエンスエクスポート診断を実行します。 | | `ga4_get_audience_diagnostics` | Admin API のオーディエンス、Data API の定期オーディエンスリスト、および観測された audienceName レポートへのフォールバックから、読み取り専用のオーディエンス診断を実行します。 | | `ga4_get_bigquery_export_diagnostics` | GA4 BigQuery エクスポートリンクを検出し、エクスポートモード、ストリームのカバレッジ、除外イベント、データセットのロケーションを診断します。 | | `ga4_get_server_side_tagging_diagnostics` | データストリーム、Measurement Protocol シークレット、イベントルール、ストリーム設定から、可能な範囲で読み取り専用のサーバーサイドタグ付け診断を実行します。 | | `ga4_run_advanced_funnel_report` | GA4 Data API v1alpha の runFunnelReport エンドポイントを実行します。オプションで内訳／次のアクションを指定でき、利用できない場合は読み取り専用のステップ数にフォールバックします。 | | `ga4_get_channel_groups` | GA4 プロパティに定義されているカスタムチャネルグループを一覧表示します。 | | `ga4_validate_query` | 実行前に、指標とディメンションの組み合わせを検証します。 | | `ga4_run_pivot_report` | ネイティブフィルター、並べ替え、割り当て状態、複数の日付範囲、および最大 250,000 個のピボットセルに対応した、読み取り専用の GA4 Data API ピボットレポートを実行します。 | | `ga4_batch_run_reports` | 公式 Data API のバッチリクエスト 1 件で、同じプロパティに対する独立した読み取り専用の GA4 Core レポートを 1～5 件実行します。 | | `ga4_batch_run_pivot_reports` | 公式 Data API のバッチリクエスト 1 件で、同じプロパティに対する独立した読み取り専用の GA4 ピボットレポートを 1～5 件実行します。 | | `ga4_check_compatibility` | 提案された Core レポートの選択内容と互換性のあるディメンションおよび指標を、公式 GA4 Data API に問い合わせます。 | | `ga4_get_property_quotas_snapshot` | 公式 v1alpha エンドポイントから、現在の GA4 Data API プロパティの割り当てスナップショットを読み取ります。 | | `ga4_list_accounts` | 認証済みユーザーがアクセス可能な GA4 Analytics Admin アカウントを未加工の形式で一覧表示します（読み取り専用、自動ページネーション対応）。 | | `ga4_list_admin_resources` | 許可リストに登録された GA4 Admin コレクションを読み取り専用モードで一覧表示します。対象はストリーム、カスタム定義、キーイベント、オーディエンス、プロダクトリンク、アノテーション、チャネルグループ、拡張データセット、サブプロパティ／ロールアップ設定、アクセスバインディングです。 | | `ga4_get_property_configuration` | GA4 プロパティの詳細と、選択した単一の Admin 設定（アトリビューション、データ保持、Google Signals、レポート用 ID、またはユーザー提供データ設定）を読み取ります。 | | `ga4_list_audience_exports` | 新しいエクスポートを作成せずに、既存の GA4 Audience Export スナップショットと定期オーディエンスリストを一覧表示します。 | | `ga4_query_audience_export` | 既存の GA4 Audience Export から行をクエリします。 |

6 個のリソース

| URI | 内容 | |---|---| | `ga4://manifest` | このサーバーが提供する内容と、最初に実行するツール | | `ga4://metrics` | カテゴリと形式を含む全51件の指標 | | `ga4://dimensions` | 有効な場所を含む全62件のディメンション | | `ga4://compatibility` | 互換性マトリックス | | `ga4://recipes` | 12件のステップごとのワークフロー | | `ga4://p2-diagnostics` | 診断プレイブック |

---

セキュリティ

• クライアントシークレットとリフレッシュトークンは、どのログレベルでもログに記録されず、ディスクにも書き込まれません。
• 失効したリフレッシュトークンは一度だけ報告されます。 Google が invalid_grant を返すと、それ以降の呼び出しでは再認証の手順を含む同じメッセージが返され、サーバーは再起動するまで Google にトークンを要求しません。
• プロパティを制限できます。 GA4_PROPERTY_IDS が設定されている場合、別のプロパティを指定する呼び出しはリクエストを送信する前に拒否され、検出結果には許可されたプロパティのみが表示されます。
• 接続先は3つのホストのみです：analyticsdata.googleapis.com、analyticsadmin.googleapis.com、oauth2.googleapis.com。ソースに4つ目のホストが現れると、テストによってビルドが失敗します。
• リダイレクト先へのフェッチは行いません。 すべての送信呼び出しで redirect: "error" を設定しているため、リダイレクトによってベアラートークンやクライアントシークレットが別のホストに転送されることはありません。フェッチでこれが省略されると、テストによってビルドが失敗します。
• テレメトリーはありません。 サーバーが Google 以外にネットワークリクエストを送信することはありません。

個人データの取り扱い方法を含むポリシーの全文：SECURITY.md。

---

マネージド型のマルチプラットフォーム版をお探しですか？

ローカルサーバーを運用せずにこのソースを使用したい場合は、ホスト版 GA4 をお試しください。 getmcpads は、1つの MCP URL を通じて広告、Search Console、GA4 にも接続します。 ソースの利用可否とプランの制限はサイトに記載されています。アカウントの接続は引き続き必要です。

1. GA4 接続ガイドに従います。
2. アシスタントに読み取りを許可するアカウントまたはプロパティを選択します。
3. Claude、 ChatGPT または Codexを接続します。
4. 読み取り専用のレビューを試します：「獲得チャネル、ランディングページ、設定済みの重要なイベントを比較してください。不足しているデータを明示し、何も変更しないでください。」

有料プランを選択する前に、現在のホスト版ツールカタログと料金をご確認ください。 この Apache 2.0 アダプターは、ご自身の認証情報を使用して独立して利用できます。

---

貢献

Issue とプルリクエストを歓迎します。CONTRIBUTING.mdをご覧ください。 セキュリティに関する報告を行う前に、SECURITY.mdをお読みください。

ライセンス

Apache License 2.0。NOTICEもご覧ください。

Google、Google Analytics、GA4 は Google LLC の商標です。 このプロジェクトは Google LLC と提携、承認、または後援を受けていません。 公開 API を利用する独立したクライアントです。

MCP コントラクトとデスクトップバンドル

すべてのツールは、読み取り／書き込みのアノテーション、パラメーターの説明、構造化出力スキーマを宣言します。成功した呼び出しではペイロードが structuredContent.result として公開され、エラーでは isError: true が保持されます。生成されるサーバーカードには定義のみが含まれます。

npm run bundle -- /path/to/output を実行すると、現在のカタログから .mcpb デスクトップバンドルをビルドできます。認証情報はインストール時にローカルで入力します。このサーバーは引き続き読み取り専用です。

More from getmcpads

Meta Ads · Google Ads · Google Search Console · TikTok Ads · Pinterest Ads · X Ads

Maintained by Emmanuel at getmcpads. Questions: [email protected].