GA4 Analytics MCP V2

Multi-operator Google Analytics 4 connector for Claude.ai Custom Connectors, hosted on Google Cloud Run.

This is Version 2. It is a separate application from V1. Do not reuse V1 secrets, OAuth clients, Cloud Run services, or Git remotes.

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

There is no local stdio server and no Supabase.

Architecture

Two OAuth layers are linked:

1. Claude → V2: MCP OAuth 2.1 (protected resource metadata, DCR, CIMD, PKCE).

2. V2 → Google: Google sign-in happens inside MCP authorize. The MCP access token sub is the Google account subject (sub). Email is display-only.

Each operator has:

• their own encrypted Google refresh token

• their own accessible GA4 property list (from Google Admin API)

• their own persisted active property

Operator A cannot use Operator B's Google credential or select a property that Google account A cannot access.

MCP tools

Report tools use the stored active property when propertyId is omitted. A supplied propertyId is accepted only if the authenticated Google account can access it, and then becomes the new active property.

Local development

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

Fill in .env.local with V2 values. Do not copy V1 secrets.

Optional Firestore emulator:

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

Set FIRESTORE_EMULATOR_HOST=localhost:8080 and FIRESTORE_PROJECT_ID in .env.local.

npm run dev
npm test
npm run build

• App: http://localhost:3000

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

• Health: http://localhost:3000/health

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

Claude.ai cannot reach localhost. Deploy V2 to Cloud Run before adding the Custom Connector.

Environment variables

V2 does not use GOOGLE_REFRESH_TOKEN or MCP_AUTH_TOKEN.

Google Cloud configuration

Use a new Google Cloud project when possible. If you share a project with V1, still create a distinct Cloud Run service, Artifact Registry repo, OAuth client, and secrets.

Enable:

• Cloud Run

• Cloud Build

• Artifact Registry

• Firestore

• Secret Manager

• Google Analytics Admin API

• Google Analytics Data API

Suggested resource names (placeholders — replace with your project):

• Cloud Run service: ga4-mcp-v2

• Artifact Registry: ga4-mcp-v2

• Firestore collection: operators

Cloud Run service account should have:

• roles/datastore.user on the V2 Firestore database

• roles/secretmanager.secretAccessor on V2 secrets only

Do not grant the service account Secret Manager admin or access to V1 secrets.

Google OAuth client (V2 only)

Create a new OAuth Web application. Do not edit the V1 client.

Consent screen:

• User type: External (or Internal for Workspace-only)

• App name: something like GA4 MCP Connector V2

• Scopes:

  • openid

  • email

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

• Add test users while the app is in Testing

• Publishing is required for non-test users because Analytics scopes are sensitive

Authorized redirect URI:

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

Locally:

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

Claude Custom Connector

1. Deploy V2 and set APP_BASE_URL to the Cloud Run URL.

2. In Claude, add a Custom Connector.

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

4. Each operator completes Google sign-in from their own Claude account.

5. If the Google account has multiple GA4 properties, they pick one. That choice persists until they switch.

Testing

npm test

Unit tests cover:

• MCP OAuth metadata, DCR, PKCE, and Google-bound JWT sub

• Operator isolation (credentials and property allow-lists)

• Persistent active property

• Token refresh / rotation

• Revoked Google grants

• Structured log redaction

No live V1 credentials are used.

Deployment (do not run until requested)

Documented only. V1 deployment must stay untouched.

.\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

Prefer Secret Manager references for production secrets instead of plaintext env values when you wire the service.

After deploy:

1. Add the Cloud Run callback URI to the V2 OAuth client.

2. Confirm Firestore is created in Native mode.

3. Add https://<v2-host>/mcp in Claude.

Security considerations

• Refresh tokens are encrypted with AES-256-GCM before Firestore writes.

• MCP tools never return access tokens, refresh tokens, or authorization codes.

• Logs redact tokens, secrets, cookies, and authorization codes.

• Property IDs from Claude are checked against the live Admin API list for that operator.

• Tools fail closed if no operator context is bound to the request.

• HTTPS-only cookies in production.

Git

This repository is V2 only. The V1 remote is git@github.com:devopsbrandmirchi/Ga4McpServer.git and must never be added here. Create a new GitHub repository when you are ready to publish V2.