GA4 MCP Server

プロダクション対応、マルチテナントのGoogle Analytics 4 MCPサーバー（Claude用）。

これはより大きなプラットフォームにおける最初のコネクターです。共有インフラ（認証、クライアント、Google OAuthトークンストレージ、認可、ログ、エラー）は再利用可能です。GA4固有のコードはsrc/connectors/ga4とsrc/mcp/ga4に置かれます。これをモノリシックなGoogle Marketing MCPとして扱わないでください。

アーキテクチャ

Claude
  |  MCP OAuth 2.1 + Streamable HTTP
  v
Next.js / Vercel  (/mcp)
  |-- MCP tools (ga4_*)
  |-- Authorization (client_members only)
  |-- GA4 service
  |-- Google OAuth token manager
  v
Supabase
  |-- clients
  |-- client_members   (application identity)
  |-- google_connections (Google credential, not app identity)
  |-- ga4_properties

アプリケーションユーザーはSupabase Authユーザーです。テナントアクセスはのみclient_members(user_id, client_id, role)です。Google接続アカウントはクライアント所有の認証情報であり、アプリケーションユーザーになることはありません。

ローカルセットアップ

npm install
cp .env.example .env.local
# fill in the values documented below
npx supabase start   # or link a remote project
npx supabase db reset --local
npm run dev

http://localhost:3000を開き、アプリケーションアカウントを作成し、クライアントを作成して、Google Analyticsに接続します。

Google Cloudセットアップ

1. Google Cloudプロジェクトを作成または選択します。

2. Google Analytics Data APIとGoogle Analytics Admin APIを有効にします。

3. OAuth同意画面を構成します（外部または内部）。

4. OAuth 2.0 クライアントID認証情報（ウェブアプリケーション）を作成します。

5. 認証済みリダイレクトURI：

   • ローカル：http://localhost:3000/api/auth/google/callback

   • プロダクション：https://<your-domain>/api/auth/google/callback

6. GA4スコープのみをリクエストします：

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

   • openid

   • email

このコネクターにDV360またはGoogle Adsのスコープを追加しないでください。

GA4セットアップ

1. このアプリにメール/パスワードでサインインします（アプリケーションID）。

2. クライアントを作成します（client_membersでownerになります）。

3. 他のアプリケーションユーザーをownerまたはmemberとして追加できます。

4. Google Analyticsに接続をクリックします。これにより、Google認証情報がクライアントにアタッチされます。

5. そのGoogleアカウントから見つかった1つ以上のGA4プロパティをリンクします。

「Connect」をクリックしなかったメンバーでも、client_members行があればクエリを実行できます。

Supabaseセットアップ

このリポジトリにはsupabase/migrationsにSQLマイグレーションが含まれています。CLIで作成してください。ファイル名を独自に発明しないでください。

ローカル：

npx supabase start
npx supabase db reset --local

リモート：

npx supabase link --project-ref <project-ref>
npx supabase db push

サービスロールキーはサーバー専用です。SUPABASE_SERVICE_ROLE_KEYやGoogleリフレッシュトークンをブラウザに公開しないでください。

環境変数

.env.exampleを参照してください。必須：

.envにGA4プロパティIDを入れないでください。プロパティはSupabaseのクライアントに属します。

トークン暗号化キーを生成：

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

MCPセットアップ（Claude）

リモートエンドポイント：

https://<your-domain>/mcp

このサーバーはMCP OAuth 2.1を実装しています：

• 保護リソースメタデータ：/.well-known/oauth-protected-resource

• 認可サーバーメタデータ：/.well-known/oauth-authorization-server

• 認可：/oauth/authorize（アプリケーションログイン + 同意）

• トークン：/oauth/token（authorization_code + refresh_token、PKCE S256）

• 登録：/oauth/register（DCRフォールバック）

• CIMDがアドバタイズされます（client_id_metadata_document_supported）

Claudeで：設定 → コネクター → カスタムコネクターを追加 → https://<your-domain>/mcpを貼り付けます。ClaudeがOAuthを実行します。承認後、ツールが利用可能になります。

ローカルインスペクター：

npx @modelcontextprotocol/inspector

Streamable HTTPでhttp://localhost:3000/mcpに接続します。それでもOAuthフローからの有効なMCP Bearerトークンが必要です。

ツール

すべてのツールはclient_idを必要とします。プロパティスコープのツールはリンクされたproperty_idも必要とします。認可は常にGoogleが呼び出される前にclient_membersをチェックします。

例：ga4_run_report

{
  "client_id": "11111111-1111-1111-1111-111111111111",
  "property_id": "123456789",
  "date_start": "2026-08-01",
  "date_end": "2026-08-15",
  "dimensions": ["country"],
  "metrics": ["activeUsers", "sessions", "totalRevenue"],
  "limit": 10
}

例：ga4_compare_periods

{
  "client_id": "11111111-1111-1111-1111-111111111111",
  "property_id": "123456789",
  "current_start": "2026-08-01",
  "current_end": "2026-08-15",
  "previous_start": "2026-07-17",
  "previous_end": "2026-07-31",
  "metrics": ["activeUsers", "sessions", "totalRevenue"]
}

すると、Claudeは次のような質問に答えることができます：

• 昨日のユーザー数は？

• 今月のトップ10カ国

• 今月と先月の比較

• 現在サイトにアクティブユーザーは何人？

テスト

npm test

テストはモックされたGoogleとSupabaseを使用します。プロダクションのOAuthトークンは決して使用しません。

Vercel

Next.jsアプリをデプロイし、同じ環境変数を設定します。MCP_BASE_URLとGOOGLE_REDIRECT_URIはプロダクションドメインを使用する必要があります。/mcpルートはNode.jsランタイムで60秒の最大継続時間で実行されます。

プロジェクト構成

src/
  auth/              application authentication
  authorization/     authorizeClient via client_members
  oauth/             Google OAuth + token manager
  mcp-oauth/         MCP OAuth 2.1 authorization server
  connectors/ga4/    Google Analytics APIs
  mcp/ga4/           MCP tools
  repositories/      Supabase data access
  app/mcp/           Streamable HTTP transport

将来のコネクター（DV360、Google Ads）はsrc/connectors/<name>とsrc/mcp/<name>を追加し、共有コアを再利用する必要があります。汎用的なGoogle APIのダンプグラウンドを作成しないでください。