mcp-google-analytics

MCP Google Analytics Server

Google Analytics 4 用の Model Context Protocol（MCP）サーバーです。レポートの読み取りに使用する Google Analytics Data API と、イベントの送信に使用する Measurement Protocol v2 の両方を包括的に統合します。

読み取りと書き込みの両方に対応する GA4 MCP です。 Google 公式のものを含む、ほとんどの GA4 MCP サーバーは読み取り専用です。このサーバーを使えば、AI エージェントが一連の操作をすべて実行できます。レポートやファネルの実行、設定の監査（カスタムディメンション、キーイベント、互換性チェック）、サーバーサイドでの e コマースイベントとコンバージョンイベントの送信、リアルタイムレポートでの確認まで、npx コマンドひとつで 26 個のツールを利用できます。

代理店にも最適です：すべての読み取りツールで propertyId を省略可能なパラメーターとして指定できるため、クライアントごとに再設定することなく、ひとつの会話で全クライアントのプロパティを照会できます。マルチプロパティモードをご覧ください。

⚡ ワンクリックインストール

開始に必要なのは 2 つの値 だけです（他の GA4 MCP と同じです）。サービスアカウントの JSON とプロパティ ID を用意してください。イベントの送信は任意です。

Install in Cursor をクリックして、次の値を入力します。

1. GA_SERVICE_ACCOUNT_JSON — ダウンロードしたキー ファイルのパス、または JSON そのもの
2. GA_PROPERTY_ID — GA4 の [管理] → [プロパティ設定] にある数値 ID（例：123456789）

これだけで「今週の国別ユーザー数は？」と質問できます。イベントも送信する場合は、後から 2 つのキーを追加してください（イベントを送信する（任意）をご覧ください）。

💡 レポートを小さく保つ

レポートは大きくなることがあります。このサーバーはトークンの最適化を考慮して設計されています。

• すべての読み取りツールのデフォルト結果数は 10 件です — 必要に応じて limit パラメーターを調整してください
• 具体的な日付範囲を指定してください — 一度に何年分ものデータを照会するのは避けてください
• 必要なディメンションと指標だけを選択してください — すべてをリクエストしないでください
• 詳しいベストプラクティスは TOKEN_OPTIMIZATION.md をご確認ください

トークン使用量を最小限に抑える方法については、専用のトークン最適化ガイドをご覧ください。

🚀 クイックスタート

5 分で完了するセットアップガイドは QUICKSTART.md をご覧ください。または、以下のインストール手順に従ってください。

📦 インストール

オプション 1：npm でグローバルにインストールする

npm install -g mcp-google-analytics

オプション 2：npx で使用する（インストール不要）

npx mcp-google-analytics

🔧 設定

まずは 2 つの値を設定してください。 これでレポート、ファネル、リアルタイムデータ、プロパティ監査など、多くのユーザーに必要な機能をすべて利用できます。他の GA4 MCP と同じ設定です。

1. サービスアカウントキー

1. Google Cloud Console で Google Analytics Data API を有効にします。
2. [IAM と管理] → [サービス アカウント] → [作成] の順に進み、JSON キーをダウンロードします。
3. GA4 で、[管理] → [プロパティのアクセス管理] を開き、サービスアカウントのメールアドレスを 閲覧者 として追加します。

ファイルパスを指定するか、JSON を GA_SERVICE_ACCOUNT_JSON に貼り付けます。

2. プロパティ ID

GA4 の [管理] → [プロパティ設定] → プロパティ ID（数字のみ。例：123456789）。

{
  "mcpServers": {
    "google-analytics": {
      "command": "npx",
      "args": ["-y", "mcp-google-analytics"],
      "env": {
        "GA_SERVICE_ACCOUNT_JSON": "/path/to/service-account.json",
        "GA_PROPERTY_ID": "123456789"
      }
    }
  }
}

これで、「今週の国別アクティブユーザー数を表示して」と質問できます。

イベントの送信（任意）

エージェントにイベント（購入、登録、カスタムイベント）を記録させたい場合のみ設定してください。ほとんどの GA4 MCP では対応していません。これは追加機能であり、必須ではありません。

1. GA4 Admin → Data Streams → 対象のストリームに移動し、Measurement ID（G-XXXXXXXXXX）をコピーします。
2. Measurement Protocol API secrets → Create に移動し、シークレットをコピーします。

すでに設定している 2 つの値の横に、これらを追加します。

"GA_MEASUREMENT_ID": "G-XXXXXXXXXX",
"GA_API_SECRET": "your-api-secret"

🏢 マルチプロパティモード（代理店向け）

すべての読み取りツールでは、設定済みの GA_PROPERTY_ID を上書きする任意の propertyId 引数を指定できます。これにより、クライアントごとに再設定することなく、1 つの会話からサービスアカウントがアクセスできる任意のプロパティをクエリできます。

1. 各クライアントの GA4 プロパティ（またはアカウントレベル）で、サービスアカウントに「Viewer」権限を付与します。
2. GA_SERVICE_ACCOUNT_JSON のみ設定します（GA_PROPERTY_ID は任意となり、設定した場合はデフォルトとして使用されます）。
3. プロパティを確認してから、任意のプロパティをクエリします。

Show me all my accounts and properties          → ga_get_account_summaries
Compare last week's active users between the    → ga_run_report with propertyId "111111"
Acme property and the Globex property             and again with propertyId "222222"

propertyId には、123456789 と properties/123456789 のどちらも指定できます。イベント送信（Measurement Protocol）は、設定済みの GA_MEASUREMENT_ID／GA_API_SECRET に関連付けられたままです。各データストリームにはそれぞれ独自のシークレットがあるためです。

🔌 Claude Desktop との統合

Claude Desktop の設定ファイルに追加します。

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "google-analytics": {
      "command": "npx",
      "args": ["-y", "mcp-google-analytics"],
      "env": {
        "GA_SERVICE_ACCOUNT_JSON": "/path/to/service-account.json",
        "GA_PROPERTY_ID": "123456789"
      }
    }
  }
}

または、グローバルにインストールした場合：

{
  "mcpServers": {
    "google-analytics": {
      "command": "mcp-google-analytics",
      "env": {
        "GA_SERVICE_ACCOUNT_JSON": "/path/to/service-account.json",
        "GA_PROPERTY_ID": "123456789"
      }
    }
  }
}

設定を更新した後、Claude Desktop を再起動します。

🎯 Cursor との統合

Cursor の MCP 設定ファイルに追加します。

macOS/Linux：~/.cursor/mcp.json Windows：%USERPROFILE%\.cursor\mcp.json

{
  "mcpServers": {
    "google-analytics": {
      "command": "npx",
      "args": ["-y", "mcp-google-analytics"],
      "env": {
        "GA_SERVICE_ACCOUNT_JSON": "/path/to/service-account.json",
        "GA_PROPERTY_ID": "123456789"
      }
    }
  }
}

設定を更新した後、Cursor を再起動します。

🛠️ 利用可能なツール

概要

データの読み取り（Google Analytics Data API） — トークンを節約するため、すべての読み取りツールではデフォルトで 10 行を返します。

ツール	用途	備考
ga_run_report	ディメンションと指標を指定したカスタムレポート	必要に応じて limit を調整します
ga_run_realtime_report	リアルタイムデータ（直近 30 分間）	送信したイベントの確認に便利です
ga_get_metadata	利用可能なすべてのディメンションと指標	応答が大きいため（500 件以上）、必要な場合のみ使用してください
ga_list_accounts	アクセス可能な GA アカウントの一覧
ga_list_properties	GA4 プロパティの一覧	accountId が指定されていない場合、すべてのアカウントを集約します
ga_get_property	設定済みプロパティの詳細
ga_list_data_streams	プロパティのデータストリーム	測定 ID の確認に便利です
ga_run_pivot_report	ピボットテーブルレポート	応答が非常に大きくなる場合があります
ga_run_funnel_report	イベントステップ間のファネル分析	Data API v1alpha を使用します
ga_batch_run_reports	1 回のリクエストで複数のレポートを実行	バッチあたり 2～5 件のレポートを推奨します
ga_get_account_summaries	すべてのアカウントとプロパティを 1 回の呼び出しで取得	ID を確認する最速の方法です
ga_list_custom_dimensions	プロパティのカスタムディメンション	レポートで使用する API 名を確認できます
ga_list_custom_metrics	プロパティのカスタム指標	レポートで使用する API 名を確認できます
ga_list_key_events	プロパティのキーイベント（コンバージョン）	コンバージョンとしてカウントされる内容を確認できます
ga_list_google_ads_links	プロパティにリンクされた Google Ads アカウント
ga_check_compatibility	レポート実行前にディメンションと指標の組み合わせを検証	無駄なリクエストやエラーの繰り返しを防ぎます

イベントの送信（Measurement Protocol）：

ツール	用途
ga_send_event	パラメーター付きの任意のカスタム GA4 イベント
ga_validate_event	イベントを記録せずにデバッグエンドポイントでテスト
ga_send_pageview	ページ／画面の表示
ga_send_purchase	取引情報と商品を含む e コマースの購入
ga_send_login	ユーザーのログイン
ga_send_signup	ユーザー登録
ga_send_view_item	商品／アイテム詳細の表示
ga_send_add_to_cart	カートへの追加イベント
ga_send_begin_checkout	チェックアウトの開始
ga_send_refund	全額または一部の返金

Google Analytics Data API（データの読み取り）

ga_run_report

ディメンションと指標を指定してカスタムレポートを実行します。

一般的なディメンション：date、city、country、deviceCategory、browser、pagePath、eventName、sessionSource、sessionMedium、sessionCampaignName

一般的な指標：activeUsers、sessions、screenPageViews、conversions、totalRevenue、engagementRate、averageSessionDuration

例：

{
  "dateRanges": [{"startDate": "7daysAgo", "endDate": "today"}],
  "dimensions": [{"name": "city"}],
  "metrics": [{"name": "activeUsers"}],
  "limit": 10
}

ga_run_realtime_report

リアルタイムデータを取得します（直近30分間）。

例：

{
  "metrics": [{"name": "activeUsers"}],
  "dimensions": [{"name": "country"}],
  "limit": 10
}

ga_get_metadata

プロパティで利用可能なすべてのディメンションと指標を取得します。

警告：500件以上の項目が返されます。必要な場合にのみ使用してください。

ga_list_accounts

サービスアカウントがアクセスできるすべての GA アカウントを一覧表示します。

ga_list_properties

GA4 プロパティを一覧表示します。アカウント ID で絞り込むこともできます。

ga_get_property

設定済みのプロパティの詳細を取得します。

ga_list_data_streams

設定済みのプロパティのデータストリームを一覧表示します。

ga_run_pivot_report

行と列のディメンションを指定してピボットテーブルレポートを実行します。

例：

{
  "dateRanges": [{"startDate": "7daysAgo", "endDate": "today"}],
  "dimensions": [{"name": "country"}, {"name": "deviceCategory"}],
  "metrics": [{"name": "activeUsers"}],
  "pivots": [{"fieldNames": ["deviceCategory"], "limit": 5}]
}

ga_run_funnel_report

ユーザーの進行状況を追跡するファネル分析を実行します。

注：ファネルレポートでは Data API v1alpha チャネルを使用します（Google がこの機能を公開している唯一のチャネルです）。各ステップはイベントに対応します。各ステップに eventName を設定するか、省略してステップの name をイベント名として使用します。より高度な照合には、完全な filterExpression を渡してください。

例：

{
  "dateRanges": [{"startDate": "7daysAgo", "endDate": "today"}],
  "funnelSteps": [
    {"name": "page_view"},
    {"name": "add_to_cart"},
    {"name": "begin_checkout"},
    {"name": "Purchase", "eventName": "purchase"}
  ]
}

ga_batch_run_reports

1回のリクエストで複数のレポートを実行します。

警告：大規模なデータセットが返される場合があります。バッチごとに2～5件のレポートに制限してください。

ga_get_account_summaries

アクセス可能なすべてのアカウントとそのプロパティを、1回の簡潔な呼び出しで取得します。アカウント ID とプロパティ ID をすばやく確認できます。

ga_list_custom_dimensions / ga_list_custom_metrics

プロパティに定義されているカスタムディメンションとカスタム指標を、API 名（例：customEvent:plan_type）とともに一覧表示します。これらの名前はレポートで使用できます。

ga_list_key_events

プロパティに設定されているキーイベント（コンバージョン）を一覧表示します。コンバージョンレポートを作成する前や、どのイベントを送信するか決める際に役立ちます。

ga_list_google_ads_links

プロパティにリンクされている Google Ads アカウントを一覧表示します。

ga_check_compatibility

レポートを実行する前にディメンションと指標の組み合わせが有効か確認し、無駄なリクエストやトークンを大量に消費するエラーの繰り返しを防ぎます。

例：

{
  "dimensions": [{"name": "city"}],
  "metrics": [{"name": "activeUsers"}],
  "compatibilityFilter": "COMPATIBLE"
}

Measurement Protocol（イベントの送信）

知っておくと便利です：

• イベントが標準レポートに表示されるまで数分かかりますが、リアルタイムレポート（ga_run_realtime_report）にはほぼ即座に表示されます。
• 新しいイベントを記録せずにテストするには、ga_validate_event を使用してください。
• client_id を省略すると、呼び出しごとに自動生成されます。複数のイベント（例：カートから購入までの一連の操作）を同じセッションとユーザーとして GA にまとめるには、すべての呼び出しで**同じ client_id**を渡してください。

ga_send_event

カスタムイベントを GA4 に送信します。

例：

{
  "events": [{
    "name": "button_click",
    "params": {
      "button_id": "cta_signup",
      "page": "/landing"
    }
  }],
  "user_id": "user123"
}

ga_validate_event

送信前にイベントを検証します（デバッグエンドポイントを使用）。

ga_send_pageview

ページビューイベントを送信します。

例：

{
  "page_location": "https://example.com/products",
  "page_title": "Products",
  "user_id": "user123"
}

ga_send_purchase

E コマースの購入イベントを送信します。

例：

{
  "transaction_id": "T12345",
  "value": 99.99,
  "currency": "USD",
  "items": [{
    "item_id": "SKU123",
    "item_name": "Product Name",
    "price": 99.99,
    "quantity": 1
  }]
}

ga_send_login

ログインイベントを送信します。

ga_send_signup

ユーザー登録イベントを送信します。

ga_send_view_item

商品／アイテム詳細の閲覧イベントを送信します。標準的な E コマースファネルである view_item → add_to_cart → begin_checkout → purchase を完成させます。

ga_send_add_to_cart

カートへの追加イベントを送信します。

ga_send_begin_checkout

チェックアウト開始イベントを送信します。

ga_send_refund

全額または一部返金のイベントを送信します。元の購入と同じ transaction_id を使用してください。全額返金の場合は items を省略し、一部返金の場合は items を含めてください。

例（一部返金）：

{
  "transaction_id": "T12345",
  "currency": "USD",
  "value": 49.99,
  "items": [{"item_id": "SKU123", "quantity": 1}]
}

📖 使用例

実際の使用例（スペイン語）については、EXAMPLES.md を参照してください。

例：過去7日間の国別ユーザー数を取得する

Show me active users by country for the last 7 days

Claude は ga_run_report を使用します：

{
  "dateRanges": [{"startDate": "7daysAgo", "endDate": "today"}],
  "dimensions": [{"name": "country"}],
  "metrics": [{"name": "activeUsers"}],
  "limit": 10,
  "orderBys": [{"metric": {"metricName": "activeUsers"}, "desc": true}]
}

例：購入を記録する

Send a purchase event for order #12345, $99.99 USD

Claude は ga_send_purchase を使用します：

{
  "transaction_id": "12345",
  "value": 99.99,
  "currency": "USD",
  "items": [{
    "item_id": "product_1",
    "item_name": "Example Product",
    "price": 99.99,
    "quantity": 1
  }]
}

例：イベント送信前に検証する

新しいイベントを組み込む前に実行することをおすすめします。デバッグエンドポイントでは、何も記録せずにペイロードをチェックできます。

Validate this tutorial_complete event before we send it for real

Claude は ga_validate_event を使用します：

{
  "client_id": "test.123",
  "events": [{
    "name": "tutorial_complete",
    "params": {"tutorial_id": "onboarding", "duration_seconds": 120}
  }]
}

レスポンスには検証メッセージが表示されます。リストが空の場合、イベントの形式は正しいことを意味します。

例：サーバーサイドのコンバージョントラッキング

JavaScript タグが実行されないバックエンドで発生する登録やログインを追跡します：

A user just registered with Google OAuth, record the signup in Analytics

Claude は ga_send_signup を使用します：

{
  "user_id": "user_789",
  "method": "Google"
}

例：エージェントによる完全な E コマースファネル

各呼び出しで同じ client_id を送信すると、GA はイベントを 1 つのセッションにまとめます：

Track this user's journey: they added a $49 course to the cart, started checkout, and completed the purchase

Claude はクライアント ID を再利用しながら、ga_send_add_to_cart → ga_send_begin_checkout → ga_send_purchase の順に呼び出します：

{
  "client_id": "555.1717000000",
  "currency": "USD",
  "value": 49,
  "items": [{"item_id": "course_101", "item_name": "Intro Course", "price": 49, "quantity": 1}]
}

例：自動化からカスタムイベントを送信する

AI エージェントのアクティビティやスケジュール済みジョブなど、GA が標準では検知できないものを測定します：

Log that the weekly report generator ran successfully

Claude は ga_send_event を使用します：

{
  "events": [{
    "name": "automation_run",
    "params": {"job": "weekly_report", "status": "success", "duration_ms": 5400}
  }]
}

例：1 回の会話で送信して確認する

両方の API を組み合わせて、トラッキングがエンドツーエンドで機能することを確認します：

Send a test event and confirm Analytics received it

Claude は ga_send_event を呼び出してから、ga_run_realtime_report で確認します：

{
  "dimensions": [{"name": "eventName"}],
  "metrics": [{"name": "eventCount"}],
  "limit": 10
}

Measurement Protocol のイベントは数秒以内にリアルタイムレポートに表示されますが、標準レポートへの反映には数分かかることがあります。

🔍 デバッグ

次の設定を行うと、デバッグログを有効にできます：

export DEBUG=mcp-google-analytics:*

Measurement Protocol の場合は、イベントを本番環境に送信する前に ga_validate_event を使用して確認してください。

🤝 コントリビューション

コントリビューションを歓迎します！お気軽にプルリクエストをお送りください。

📄 ライセンス

MIT License。詳細は LICENSE ファイルをご覧ください。

🔗 リンク

• GitHub リポジトリ
• npm パッケージ
• Smithery
• MCP ドキュメント
• GA4 Data API ドキュメント
• Measurement Protocol ドキュメント

🆘 サポート

問題や質問については、以下をご利用ください：

• GitHub Issues
• MCP Community Discord

📝 変更履歴

バージョン履歴については、CHANGELOG.md をご覧ください。

---