ga4

mcp-ga4

Claude を介してレポート、リアルタイムデータ、カスタムディメンション、プロパティ管理を実行する Google Analytics 4 用 MCP サーバーです。

機能

• レポート、リアルタイムデータ、カスタムディメンション／指標、データストリーム、フィードバックをカバーする 9 個のツール
• 2 つの設定モード：単一プロパティ（環境変数）と複数クライアント（config.json）
• サービスアカウントと OAuth 認証情報の両方に対応
• 相対日付に対応（today、yesterday、7daysAgo、30daysAgo、90daysAgo）
• 公式 Google SDK を基盤とし、レジリエンスパターンを採用

クイックスタート

1. 認証情報を取得します。サービスアカウントのキーファイル、またはユーザー OAuth のリフレッシュトークンを用意します （認証を参照）。

2. このマシン上の各 Claude クライアントにサーバーを登録します：

   # service account
   npx -p mcp-ga4 mcp-ga4-setup --property-id 123456789 --credentials /path/to/service-account.json
   
   # or user OAuth: export GA4_CLIENT_ID / GA4_CLIENT_SECRET / GA4_REFRESH_TOKEN first
   npx -p mcp-ga4 mcp-ga4-setup --property-id 123456789
   

   ウィザードは Claude Desktop（macOS では ~/Library/Application Support/Claude/claude_desktop_config.json、Windows では %APPDATA%\Claude\claude_desktop_config.json）と Claude Code CLI（PATH 上の claude）を検出し、見つかった各クライアントに ga4 を登録します。Desktop 設定内の他のサーバーや設定は保持されます。設定ファイルが無効な場合は変更せず、ウィザードを停止します。再実行しても安全です。いずれか 1 つのクライアントを対象にするには、--claude-desktop-only または --claude-code-only を使用します。

3. Claude Desktop を完全に終了して再起動する（Cmd+Q）か、claude セッションを再起動します。

インストール

npm install mcp-ga4

または、リポジトリをクローンします：

git clone https://github.com/mharnett/mcp-ga4.git
cd mcp-ga4
npm install
npm run build

認証

mcp-ga4 は2 種類の認証情報に対応しています。選択は決定的で、起動時に一度だけ行われます。明示的に指定されたキーファイル／サービスアカウントが優先され、次にユーザー OAuthが選ばれます。どちらも設定されていない場合、両方の選択肢を明記したオンボーディングエラーを出力してサーバーは終了します。コードにマシンローカルの認証情報パスは組み込まれておらず、実行時に無言で別の方式へ切り替わることもありません。認証情報の入力元は環境変数と、必要に応じてユーザー自身の config.json のみです。（そのため、後で 403 が発生した場合は API エラーとして表示され、もう一方の認証方式へ無言で切り替わることはありません。）

優先順位： 両方の認証方式が設定されている場合、ユーザー OAuth よりキーファイル／サービスアカウントが優先されます。

オプション A：サービスアカウント（常時稼働／サーバー用途に推奨）

常時稼働する環境やサーバーへのデプロイには、こちらを使用します。 GOOGLE_APPLICATION_CREDENTIALS（または config.json の credentials_file）に JSON キーファイルを指定します。サービスアカウントには、GA4 プロパティへのアクセス権を付与する必要があります（管理 → プロパティのアクセス管理 → サービスアカウントのメールアドレスを追加し、少なくとも閲覧者の権限を付与）。リフレッシュトークンは不要です。サーバーはキーファイルを直接 GA4 SDK に渡します：

GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

キーファイルには、実際のサービスアカウントキーと authorized_user OAuth トークンダンプのどちらも使用できます。どちらも keyFile オプションで受け付けられます。

オプション B：ユーザー OAuth（個人利用／対話型利用）

サーバーを Google のユーザー（自分自身の GA4 ログイン）として動作させる場合は、こちらを使用します。Google OAuth クライアントを自分で用意し、リフレッシュトークンを一度発行します。

1. Google Cloud Console で、タイプが デスクトップアプリの OAuth 2.0 クライアント IDを作成します。Google Analytics Data APIを有効にします（カスタムディメンション用ツールを使用する場合は、Admin APIも有効にします）。

2. クライアント認証情報をエクスポートし、トークンヘルパーを実行します（PKCE を使用し、ブラウザーを開いて、トークンを標準出力に表示します）：

   export GA4_CLIENT_ID=...            # from the Desktop-app client
   export GA4_CLIENT_SECRET=...
   node get-refresh-token.cjs          # or: npm run auth
   

   このコマンドの標準出力を共有ログにリダイレクトしないでください。リフレッシュトークンが意図的にそこへ出力されます。

3. 表示された GA4_REFRESH_TOKEN=... を環境変数にコピーします。実行時にサーバーは次の 3 つの環境変数を読み取ります：

   GA4_CLIENT_ID=...
   GA4_CLIENT_SECRET=...
   GA4_REFRESH_TOKEN=...
   

要求するスコープは config.json の oauth.scope から読み取られます（以下を参照）。そのため、ヘルパーと実行中のサーバーで、許可されたスコープが食い違うことはありません。

スコープ（最小限の付与）

スコープは config.json の oauth.scope に設定します。コミットされているデフォルト値は次のとおりです。

https://www.googleapis.com/auth/analytics.readonly
https://www.googleapis.com/auth/analytics.edit

ga4_create_custom_dimension は Admin API を介してプロパティを変更するため、analytics.edit が必要です。読み取りアクセスのみが必要な場合は、独自の config.json で oauth.scope を analytics.readonly のみに上書きし、ヘルパーを再実行してください。

設定

セキュリティ： .mcp.json ファイルを共有したり、git にコミットしたりしないでください。API 認証情報が含まれている場合があります。.mcp.json を .gitignore に追加してください。

モード 1：単一プロパティ（環境変数）

プロパティ ID と、上記の認証方式のいずれかを設定します。

GA4_PROPERTY_ID=123456789
# then EITHER the OAuth trio (GA4_CLIENT_ID/SECRET/REFRESH_TOKEN)
# OR a service account: GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

モード 2：複数クライアント（config.json）

プロジェクトのルートに config.json を作成し、複数の GA4 プロパティをプロジェクトディレクトリに対応付けます。サーバーは呼び出し元の作業ディレクトリに基づいて、使用するプロパティを自動検出します。認証情報は環境変数から取得します（上記のオプション A／B）。config.json には、設定ファイルのみを使用する SA 構成用のサービスアカウントパス credentials_file を任意で指定できます。

{
  "oauth": {
    "scope": "https://www.googleapis.com/auth/analytics.readonly https://www.googleapis.com/auth/analytics.edit"
  },
  "clients": {
    "client-a": {
      "name": "Client A",
      "folder": "/path/to/client-a/project",
      "property_id": "123456789"
    },
    "client-b": {
      "name": "Client B",
      "folder": "/path/to/client-b/project",
      "property_id": "987654321"
    }
  }
}

使用方法

手動設定

mcp-ga4-setup（クイックスタートを参照）がこの設定を書き込みます。エントリを手動で管理する場合、単一プロパティの形式は次のとおりです。

{
  "mcpServers": {
    "ga4": {
      "command": "npx",
      "args": ["mcp-ga4"],
      "env": {
        "GA4_PROPERTY_ID": "123456789",
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/credentials.json"
      }
    }
  }
}

複数クライアントモード：

{
  "mcpServers": {
    "ga4": {
      "command": "node",
      "args": ["/path/to/mcp-ga4/dist/index.js"]
    }
  }
}

同じ mcpServers 形式が、Claude Code のプロジェクト設定と Claude Desktop の claude_desktop_config.json で使用されます。

一般的なクエリパターン

上位のページ： dimensions=pagePath、metrics=screenPageViews、order_by=screenPageViews

トラフィックソース： dimensions=sessionSource,sessionMedium、metrics=sessions,totalUsers

日別の推移： dimensions=date、metrics=sessions,totalUsers

キャンペーンのパフォーマンス： dimensions=sessionCampaignName、metrics=sessions,conversions

デバイス別内訳： dimensions=deviceCategory、metrics=sessions,totalUsers

ツール

ツール	説明
ga4_get_client_context	アクティブな GA4 プロパティ ID とクライアント名を返します
ga4_run_report	ディメンション、指標、期間、フィルターを指定して、標準的な GA4 レポートを実行します
ga4_realtime_report	リアルタイムデータ（直近 30 分間）をクエリします
ga4_list_custom_dimensions	プロパティのカスタムディメンションをすべて一覧表示します
ga4_create_custom_dimension	新しいカスタムディメンションを作成します
ga4_list_custom_metrics	プロパティのカスタム指標をすべて一覧表示します
ga4_list_data_streams	ウェブ／アプリのデータストリームと測定 ID を一覧表示します
ga4_send_feedback	クエリ結果に関するフィードバックを送信します
ga4_suggest_improvement	新しいクエリパターンや改善案を提案します

日付形式

絶対日付には YYYY-MM-DD を使用するか、次の相対日付のショートカットを使用します。

• today
• yesterday
• 7daysAgo
• 30daysAgo
• 90daysAgo

一般的なディメンションと指標

ディメンション： date、dateHour、eventName、pagePath、pageTitle、sessionSource、sessionMedium、sessionCampaignName、country、city、deviceCategory、browser、operatingSystem、landingPage、pageReferrer、newVsReturning、firstUserSource、firstUserMedium、firstUserCampaignName

指標： sessions、totalUsers、newUsers、activeUsers、screenPageViews、eventCount、conversions、engagedSessions、engagementRate、averageSessionDuration、bounceRate、sessionsPerUser、screenPageViewsPerSession、userEngagementDuration

データの鮮度

• 標準レポート：24～48 時間の遅延
• リアルタイムレポート：直近 30 分間のみ

アーキテクチャ

以下を基盤としています。

• @google-analytics/data -- レポート用の GA4 Data API
• @google-analytics/admin -- プロパティ管理用の GA4 Admin API
• cockatiel -- レジリエンス（再試行、サーキットブレーカー）
• pino -- 構造化ログ

ライセンス

MIT

作者

Mark Harnett / drak-marketing が開発