Google Analytics 4

@mindstone/mcp-server-google-analytics

Model Context Protocol ホスト向けの Google Analytics 4 MCP サーバーです。アカウントとプロパティの構成を確認し、ライブスキーマを調べ、安全のための行数制限付きでレポートを実行し、大規模な非同期エクスポートを作成し、標準化された MCP インターフェースを通じて管理設定を確認できます。

ステータス

• バージョン： 0.2.1 · npm
• 認証： Google ADC による OAuth（GOOGLE_APPLICATION_CREDENTIALS）
• ツール： 34（アカウント、スキーマ、レポート、管理）
• 提供形態： クラウド API
• 機械可読： STATUS.json

要件

• Node.js 20+
• npm
• analytics.readonly スコープを持つ Google Application Default Credentials（ADC）、または GA4 プロパティへのアクセス権を持つサービスアカウント JSON

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

ボタンをクリックすると、ホストで GOOGLE_APPLICATION_CREDENTIALS の入力を求められます。

{
  "mcpServers": {
    "Google Analytics 4": {
      "command": "npx",
      "args": [
        "-y",
        "@mindstone/mcp-server-google-analytics"
      ],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": ""
      }
    }
  }
}

クイックスタート

インストールとビルド

cd <path-to-repo>/connectors/google-analytics
npm install
npm run build

npx（公開後）

npx -y @mindstone/mcp-server-google-analytics

ローカル

node dist/index.js

認証

このサーバーは Google Application Default Credentials（ADC）を使用します。ユーザーアカウント用の ADC を発行するには、Google Cloud CLI をインストールし、次を実行します。

gcloud auth application-default login \
  --scopes=https://www.googleapis.com/auth/analytics.readonly \
  --client-id-file=/absolute/path/to/oauth-client-secret.json

--client-id-file は省略可能ですが、強く推奨されます。独自の OAuth クライアントを使用すると、共有の gcloud クォータを避けられ、安定した認証実績を得られます。Google Analytics Admin API と Google Analytics Data API を有効にした Google Cloud プロジェクトが必要です。

サービスアカウントを使用する場合は、GOOGLE_APPLICATION_CREDENTIALS にサービスアカウント JSON の絶対パスを設定します。サービスアカウントには、GA4 Admin UI で GA4 プロパティへのアクセス権を付与する必要があります。

設定

環境変数

• GOOGLE_APPLICATION_CREDENTIALS — 必須。ADC またはサービスアカウント JSON の絶対パスです。Node は ~ や %APPDATA% を展開しません。完全に解決済みのパスを指定してください。
• GA4_PROPERTY_ID — 省略可能。デフォルトの GA4 プロパティ ID（例：123456789）です。呼び出しで property_id が渡されない場合、ツールはこの値を使用します。

ホスト設定の例

Claude Desktop / Cursor

{
  "mcpServers": {
    "GoogleAnalytics": {
      "command": "npx",
      "args": ["-y", "@mindstone/mcp-server-google-analytics"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/Users/you/.config/gcloud/application_default_credentials.json",
        "GA4_PROPERTY_ID": "123456789"
      }
    }
  }
}

ローカル開発（npm への公開は不要）

{
  "mcpServers": {
    "GoogleAnalytics": {
      "command": "node",
      "args": ["<path-to-repo>/connectors/google-analytics/dist/index.js"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/credentials.json",
        "GA4_PROPERTY_ID": "123456789"
      }
    }
  }
}

ツール（34）

アカウントとプロパティ

• ga_list_account_summaries — 利用可能なアカウントとプロパティを検出します
• ga_list_properties — 任意のフィルタリングに対応した、GA4 プロパティのフラットリストを取得します
• ga_get_property_details — 通貨、タイムゾーン、業種カテゴリ、サービスレベルを取得します

スキーマの検出

• ga_get_metadata — プロパティの最新スキーマを取得します
• ga_get_property_schema — 概要件数付きで同じデータを取得します
• ga_search_schema — ディメンションと指標をキーワード検索します
• ga_list_dimension_categories、ga_list_metric_categories
• ga_get_dimensions_by_category、ga_get_metrics_by_category
• ga_check_compatibility — レポート作成前にディメンションと指標の組み合わせを検証します

レポート作成

• ga_run_report — 行数の安全対策を備えた基本レポート（推定、大規模データセットへのオプトイン、自動集計の提案）
• ga_run_pivot_report — クロス集計レポート
• ga_batch_run_reports — 1 回の呼び出しで最大 5 件のレポートを実行します
• ga_run_realtime_report — 直近 30 分間のアクティビティを取得します
• ga_get_property_quotas_snapshot — 残りのトークン数／リクエスト数を取得します

大規模エクスポート

• ga_create_report_task — 大規模エクスポート用の非同期レポートタスクを開始します（同期タイムアウトなし、行数制限なし）
• ga_get_report_task — ACTIVE になるまでタスクの状態をポーリングします
• ga_query_report_task — タスクの行をページ単位で取得します（1 ページあたり最大 250,000 行）
• ga_create_audience_export — オーディエンス内のユーザーのスナップショットを作成します（予測セグメントを含む）。オーディエンスエクスポートのクォータトークンを消費します
• ga_get_audience_export — エクスポートが ACTIVE になるまで状態をポーリングします
• ga_list_audience_exports — 既存のエクスポートを検索して再利用します
• ga_query_audience_export — ACTIVE なエクスポートからユーザーレベルの行をページ単位で取得します

管理機能の可視化

• ga_list_audiences — フィルター句を指定して、プロパティに設定されたオーディエンスを取得します
• ga_list_channel_groups — チャネルグループとそのグループ化ルールを取得します
• ga_get_custom_dimensions_and_metrics
• ga_list_google_ads_links
• ga_list_key_events
• ga_list_data_streams
• ga_get_global_site_tag — 最初のウェブストリームの gtag.js スニペットを取得します
• ga_list_bigquery_links
• ga_get_data_retention_settings
• ga_list_firebase_links
• ga_search_change_history_events

注意事項

• 読み取り専用の方針。 すべてのツールは読み取り専用です。ただし、ga_create_report_task と ga_create_audience_export は、サーバー側のスナップショットを作成してクォータを消費します（readOnlyHint: false、destructiveHint: true、idempotentHint: false として注記）。プロパティ設定は変更しません。ホスト側で、この 2 つの作成ツールを明示的なユーザー承認の後にのみ実行するよう制限できます。
• アルファ版エンドポイント。 オーディエンス、チャネルグループ、BigQuery リンク、グローバルサイトタグ、変更履歴（Admin API）、レポートタスク（Data API）は、現時点では Google の v1alpha のサーフェスでのみ公開されています。該当するツールの説明にもその旨が記載されています。
• 信頼できないコンテンツ。 GA4 プロパティ内で作成されたテキスト（レポートのディメンション値（ページタイトル、キャンペーン名、カスタムディメンション値）、オーディエンス名／表示名、説明、定義の blob、データストリームのストリームデータの blob、グローバルサイトタグのスニペット、カスタムメタデータの式、ベンダーから返されるヘッダー名／ディメンション名、ベンダーのエラーメッセージ）は、ホストが指示ではなくデータとして扱えるよう、<untrusted-content source="…"> のエンベロープ内で返されます。エージェントが後続の呼び出しを組み立てられるよう、指標値とリソース識別子はそのまま返されます。ツールに渡されるリソース ID は、URL に埋め込む前に ID の文字セットに制限されます。それ以外の値には INVALID_RESOURCE_ID が返されます。
• レスポンスの検証。 すべての Google API レスポンスは、境界で Zod スキーマに照らして検証されます。形式が一致しない場合は、不正なデータを伝播させずに INVALID_API_RESPONSE エラーで処理を終了します。ページネーション付きのリストでは nextPageToken を最後まで追跡し、安全のための十分に大きな上限を超えても API がページングを停止しない場合は、PAGINATION_LIMIT_EXCEEDED で失敗します。黙って切り詰められることはありません。

ライセンス

FSL-1.1-MIT — Functional Source License, Version 1.1（将来的に MIT ライセンスとなります）。このソフトウェアは、リリースから 2 周年を迎えると MIT ライセンスに切り替わります。