mcp-ga4

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

特徴

• レポート、リアルタイムデータ、カスタムディメンション/メトリクス、データストリーム、フィードバックをカバーする 9 つのツール

• 2 つの設定モード: シングルプロパティ (環境変数) とマルチクライアント (config.json)

• サービスアカウントと OAuth 認証情報の両方をサポート

• 相対日付のサポート (today, yesterday, 7daysAgo, 30daysAgo, 90daysAgo)

• 公式 Google SDK とレジリエンスパターンに基づいて構築

Related MCP server: Google Analytics 4 MCP Server

インストール

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 を使用し、ブラウザを開き、トークンを stdout に出力します):

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

   このコマンドの stdout を共有ログにリダイレクトしないでください -- リフレッシュトークンは設計上そこに出力されます。

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

analytics.edit は、ga4_create_custom_dimension が Admin API を介してプロパティを変更するために必要です。読み取りアクセスのみが必要な場合は、独自の 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"
    }
  }
}

使用方法

Claude Code (.mcp.json)

シングルプロパティモード:

{
  "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"]
    }
  }
}

Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) または %APPDATA%\Claude\claude_desktop_config.json (Windows) に追加します。

一般的なクエリパターン

トップページ: 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

ツール

日付形式

絶対日付には 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 によって構築