GA4 Analytics MCP V2

Claude.ai カスタムコネクタ向けの複数オペレーター対応 Google Analytics 4 コネクタです。Google Cloud Run 上でホストされています。

これはバージョン 2 です。V1 とは別のアプリケーションです。V1 のシークレット、OAuth クライアント、Cloud Run サービス、Git リモートを再利用しないでください。

Operator A or Operator B
  → same Claude Custom Connector URL
  → https://<v2-host>/mcp
  → MCP OAuth (Claude → V2)
  → Google OAuth (operator's own Google account)
  → operator credentials + active GA4 property in Firestore
  → GA4 Admin / Data APIs

ローカル向けの stdio サーバーや Supabase はありません。

アーキテクチャ

2 つの OAuth レイヤーがリンクしています:

1. Claude → V2: MCP OAuth 2.1（保護リソースメタデー、DCR、CIMD、PKCE）

2. V2 → Google: Google サインインは MCP authorize の中で 行われます。MCP アクセストークンの sr は、Google アカウントの субジェクト（sub）です。メールアダレスは表示専用です。

各オペレーター:

• 自分用に暗号化された Google リフレッシュ・トークン

• 自分だけがアクセスできる GA4 プロパティ一覧（Google Admin API から取得）

• 自分だけが保持する永続的なアクティブ・プロパティ

オペレーター A は、オペレーター B の Google 資格情報を使用したリ、Google アカウント A がアクセスできないプロパティを選択することはできません。

MCP ツール

レポート・ツルは、propertyId が省略された場合は、保存されているアクティブ・プロパティを使用します。指定された propertyId が有効になるのは、認証された Google アカウントがそのプロパティへアクセスできる場合だけです。その場合、それが新しいアクティブ・プロパティになります。

ローカル開発

cd D:\MCP_Servers\Ga4McpV2
npm install
copy .env.example .env.local

.env.local には V2 の値を入力してください。V1 のシークレットはコピーしないでください。

オプションの Firestore エミュレー ター:

gcloud emulators firestore start --host-port=localhost:8080

.env.local に FIRESTORE_EMULATOR_HOST=localhost:8080 と FIRESTORE_PROJECT_ID を設定します。

npm run dev
npm test
npm run build

• アプリ: http://localhost:3000

• MCP: http://localhost:3000/mcp

• ヘルス: http://localhost:3000/health

• Google コールバック: http://localhost:3000/oautオ/google/callback

ところが、Claude.ai は localhost に到達できません。カスーム・コネクタを追加する前に、V2 を Cloud Run にデプロイしてください。

環境変数

V2 は、GOOGLE_REFRESH_TOKEN も MCP_AUTH_TOKENも使用しません。

Google Cloud 設定

可能な場合は新しい Google Cloud プロジェクトを使用してください。V1 とプロジェクトを共有する場合でも、それ用の Cloud Run サービス、Artifact Registry リポジトリ、OAuth クライアント、シークレットを作成してください。

有効にするもの:

• Cloud Run

• Cloud Build

• Artifact Registry

• Firestore

• Secret Manager

• Google Analytics Admin API

• Google Analytics Data API

推奨されるリソース名（プレースホルダーはあなたのプロジェクトで置き換え）:

• Cloud Run サービス: ga4-mcp-v2

• Artifact Registry: ga4-mcp-v2

• Firestore コレクション: operators

Cloud Run サービスアカウントには以下が必要:

• V2 Firestore データベースに対する roles/datastore.user

• V2 のシークレットのみに対する roles/secretmanager.secretAccessor

サービスアカウントに Secret Manager 管理者権限や、V1 のシークレットへのアクセス権を付与しないでください。

Google OAuth クライアント（V2 のみ）

新しい OAuth Web アプリケーションを作成してください。V1 クライアントを編集しないでください。

Consent Screen

• ユーザータイプ: External（Workspace のみ Lite の場合は Internal）

• アプリ名: GA4 MCP Connector V2 など

• スコープ:

  • openid

  • email

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

• アプリが Testing の間はテストユーザーを追加

• Analytics のスコープは機微/sensitive なため、一般ユーザーには公開（Publishing）が必要

認証済みのリダイレクト URI:

https://<v2-cloud-run-url>/oauth/google/callback

ローカル:

http://localhost:3000/oauth/google/callback

Claude カスタムコネクタ

1. V2 をデプロイし、APP_BASE_URL を Cloud Run の URL に設定します。

2. Claude でカスタムネクタを追加します。

3. URL: https://<v2-host>/mcp

4. 各オペレーターは自分の Claude アカウントから Google サインインを行います。

5. もし Google アカウントに複数の GA4 プロパティがある場合は、オペレーターは 1 つ選択します。その選択は切り替えるまで保持されます。

テスト

npm test

ユニットテストでカバーされる内容:

• MCP OAuth メタデータ、DCR、PKCE、Google 側にバインドされた OAuth トークンの sub（サブジェクト）

• オペレーターの分離（認証情報とプロパティ許可リスト）

• 永続化された アクティブプロパティ

• トークンのリフレッシュ / ローテーション

• 取り消された Google 認可許可

• 構造化ログの 機密情報 マスキング（redaction）

ライブな V1 の認証情報は使用されません。

デプロイ（リクエストされるまで実行しないでください）

ドキュメント用のみの記述です。V1 のデプロイはそのまま変更なしに保ってください。

.\scripts\cloud-run-setup.ps1 -ProjectId YOUR_V2_PROJECT_ID
.\scripts\cloud-run-deploy.ps1 -ProjectId YOUR_V2_PROJECT_ID
.\scripts\cloud-run-set-env.ps1 `
  -ProjectId YOUR_V2_PROJECT_ID `
  -AppBaseUrl https://YOUR_V2_CLOUD_RUN_URL `
  -GoogleClientId YOUR_V2_CLIENT_ID `
  -GoogleClientSecret YOUR_V2_CLIENT_SECRET `
  -McpTokenSecret YOUR_MCP_TOKEN_SECRET `
  -OauthStateSecret YOUR_OAUTH_STATE_SECRET `
  -TokenEncryptionKey YOUR_TOKEN_ENCRYPTION_KEY

シークレットについて、本番環境ではプレーンの環境変数値ではなく、Secret Manager 参照を推奨します。

デプロイ後:

1. V2 OAuth クライアントに Cloud Run のコールバック URI を追加します。

2. Firestore がネイティブモードで作成されていることを確認します。

3. Claude に https://<v2-host>/mcp を追加します。

セキュリティ上の考慮点

• リフレッシュトークンは Firestore へ書き込む前に AES-256-GCM で暗号化されます。

• MCP ツールがアクセストークン、リフレッシュトークン、認証コードを返すことはありません。

• ログではトークン、シークレット、クッキー、認証コードがマンキングされます。

• Claude からのプロパティ ID は、そのオペレーターに対するライブ Admin API 一覧と照合されます。

• リクエストにオペレーターのコンテキストが関連付けられていない場合、ツールはフェイルクローズド（遮断モード）で動作します。

• 本番では HTTPS 限定のクッキーです。

Git

このリポジトリは V2 のみです。以前の V1 リモートは git@github.com:devopsbrandirechi/Ga4McpServer.git であり、ここには入れないでください。V2 公開時には新しい GitHub リポジトリを作成してください。