GA4 Analytics MCP

Claude.ai カスタムコネクタ向けの個人用 Google Analytics 4 コネクタ。Google Cloud Run 上でホストします。

Claude.ai Custom Connector
  → https://ga4-mcp-xxxxx-uc.a.run.app/ga4mcp
  → Cloud Run
  → Google Analytics Data API
  → your GA4 properties

ローカルの stdio サーバー、npx の要件、claude_desktop_config.json はありません。

2つの認証レイヤーは分離されています。

1. Claude → MCP: MCP OAuth（CIMD / DCR）

2. MCP → Google: GOOGLE_REFRESH_TOKEN に保存された Google OAuth リフレッシュトークン

MCP ツール

Related MCP server: Google Analytics MCP Server

ローカル開発

npm install
copy .env.example .env.local

.env.local に記入し、以下のコマンドを実行します。

npm run dev

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

• MCP: http://localhost:3000/ga4mcp

• Google OAuth: http://localhost:3000/oauth/google

• ヘルスチェック: http://localhost:3000/health

npm test
npm run build

Claude.ai は localhost に接続できません。カスタムコネクタを追加する前に、Cloud Run にデプロイしてください。

Google Cloud のセットアップ（単一プロジェクト）

API、OAuth、Cloud Run に同じ Google Cloud プロジェクトを使用します。

1. インストールとログイン

1. Google Cloud SDK をインストールします。

2. 次のコマンドを実行します。

gcloud auth login
gcloud auth application-default login

3. Google Cloud コンソールでプロジェクトを作成または選択します。

gcloud config set project YOUR_PROJECT_ID

2. API を有効化

.\scripts\cloud-run-setup.ps1 -ProjectId YOUR_PROJECT_ID -Region us-central1

これにより以下が有効になります。

• Cloud Run

• Cloud Build

• Artifact Registry

• Google Analytics Data API

• Google Analytics Admin API

またはコンソールで有効化するには、API とサービス → ライブラリ に移動します。

3. OAuth 同意画面とウェブクライアント

この Google OAuth クライアントは、Cloud Run が GA4 データを読み取るためのものです。Claude.ai の詳細設定クライアントではありません。

1. API とサービス → OAuth 同意画面 を開きます。

2. ユーザータイプ: 個人の Gmail アカウントの場合は 外部。

3. アプリ名: GA4 MCP。

4. テストモードの場合は、自分自身をテストユーザーとして追加します。

5. リフレッシュトークンが7日後に期限切れにならないよう、本番 に公開します。

6. OAuth クライアント ID の認証情報を作成します。

7. アプリケーションの種類: ウェブアプリケーション。

8. 承認済みのリダイレクト URI（両方を追加）:

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

   • https://ga4-mcp-XXXXXXXX-uc.a.run.app/oauth/google/callback
     （初回デプロイ後に実際の Cloud Run URL を使用）

9. このアプリで使用するスコープ:

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

10. クライアント ID とクライアントシークレットをコピーします。コミットしないでください。

承認する Google アカウントは、Claude がクエリする GA4 プロパティにすでにアクセス権を持っている必要があります。

Cloud Run にデプロイ

デフォルトのサービス名: ga4-mcp。デフォルトのリージョン: us-central1。

.\scripts\cloud-run-deploy.ps1 -ProjectId YOUR_PROJECT_ID -Region us-central1

スクリプトが以下を出力します。

https://ga4-mcp-XXXXXXXX-uc.a.run.app
https://ga4-mcp-XXXXXXXX-uc.a.run.app/ga4mcp
https://ga4-mcp-XXXXXXXX-uc.a.run.app/health
https://ga4-mcp-XXXXXXXX-uc.a.run.app/oauth/google/callback

サービスは 認証なしで許可 してデプロイされます。これは必須です。Claude.ai は Anthropic（160.79.104.0/21）から接続します。認証は、Cloud Run IAM ではなく、MCP_AUTH_TOKEN / MCP OAuth です。

環境変数の設定

.\scripts\cloud-run-set-env.ps1 `
  -ProjectId YOUR_PROJECT_ID `
  -AppBaseUrl "https://ga4-mcp-XXXXXXXX-uc.a.run.app" `
  -GoogleClientId "....apps.googleusercontent.com" `
  -GoogleClientSecret "...." `
  -McpAuthToken "a-long-random-string"

次に、まだ行っていない場合は、Cloud Run のコールバック URL を Google OAuth クライアントに追加します。

Google の接続

1. https://ga4-mcp-XXXXXXXX-uc.a.run.app/oauth/google を開く

2. MCP_AUTH_TOKEN を入力

3. Google アカウントでサインイン

4. 成功ページから GOOGLE_REFRESH_TOKEN をコピー

5. 設定し、Cloud Run に新しいリビジョンを開始させる。

.\scripts\cloud-run-set-env.ps1 `
  -ProjectId YOUR_PROJECT_ID `
  -AppBaseUrl "https://ga4-mcp-XXXXXXXX-uc.a.run.app" `
  -GoogleClientId "....apps.googleusercontent.com" `
  -GoogleClientSecret "...." `
  -McpAuthToken "a-long-random-string" `
  -GoogleRefreshToken "1//...."

Cloud Run はコンテナ内から環境変数を書き込めません。サーバーレスホストと同じルールです。

サービスの確認

https://ga4-mcp-XXXXXXXX-uc.a.run.app/health

次のように返される必要があります。

{"status":"ok"}

環境変数

これらを Cloud Run サービスに設定します。Git に含めないでください。

オプションのコンソールパス: Cloud Run → ga4-mcp → 編集して新しいリビジョンをデプロイ → 変数とシークレット。

Claude.ai カスタムコネクタ

1. /health が {"status":"ok"} を返すことを確認します。

2. Google OAuth を完了し、GOOGLE_REFRESH_TOKEN を設定します。

3. Claude.ai で カスタマイズ → コネクタ → カスタムコネクタを追加 を開きます。

4. 名前: GA4 Analytics

5. URL:

https://ga4-mcp-XXXXXXXX-uc.a.run.app/ga4mcp

6. 詳細設定の OAuth クライアント ID / シークレットは空のままにします。

7. 追加 をクリックします。

8. + → コネクタ でコネクタを有効にします。

9. 最初の GA4 ツール呼び出しで 接続 が表示されます。このアプリの同意画面で MCP_AUTH_TOKEN を入力します（Google パスワードではありません）。

10. 質問: 昨日のユーザー数は何人でしたか？

手動 gcloud（スクリプトを使用しない場合）

gcloud artifacts repositories create ga4-mcp --repository-format=docker --location=us-central1
gcloud builds submit --config cloudbuild.yaml --substitutions=_REGION=us-central1
gcloud run services describe ga4-mcp --region us-central1 --format="value(status.url)"
gcloud run services update ga4-mcp --region us-central1 --update-env-vars APP_BASE_URL=https://...,GOOGLE_CLIENT_ID=...,GOOGLE_CLIENT_SECRET=...,GOOGLE_REDIRECT_URI=https://.../oauth/google/callback,MCP_AUTH_TOKEN=...

セキュリティ

• Google トークン、認証コード、クライアントシークレット、MCP JWT をログに記録しないでください。

• MCP ツールはシークレットを返しません。

• GOOGLE_REFRESH_TOKEN のみが Cloud Run の環境変数として永続化されます。

• Claude が接続できるように Cloud Run のイングレスは公開されています。/ga4mcp の前に Cloud IAP / IAM ログインを配置しないでください。

• 長くランダムな MCP_AUTH_TOKEN を生成してください。

日付

GA4 にそのまま渡されます: today、yesterday、7daysAgo、30daysAgo、90daysAgo、または YYYY-MM-DD。date ディメンションは YYYYMMDD として返されます。

既知の制限

• 1つの Google アカウントと1つのリフレッシュトークン。

• Cloud Run はファイルを永続化したり、実行時に環境変数を変更したりできません。GOOGLE_REFRESH_TOKEN を設定し、新しいリビジョンをデプロイしてください。

• Google のテストモードのリフレッシュトークンは約7日後に期限切れになります。

• リアルタイムデータはおおよそ直近30分です。

• レポートサイズは最大10,000行に制限されています。

• min-instances が0の場合、コールドスタートにより数秒追加されることがあります。

Cloud Run 用に追加されたファイル