GA4 Analytics MCP

Personal Google Analytics 4 connector for Claude.ai Custom Connectors, hosted on 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

There is no local stdio server, no npx requirement, and no claude_desktop_config.json.

Two authentication layers stay separate:

1. Claude → MCP: MCP OAuth (CIMD / DCR)
2. MCP → Google: Google OAuth refresh token stored in GOOGLE_REFRESH_TOKEN

MCP tools

Tool	Purpose
ga4_list_properties	Discover properties on the connected Google account
ga4_get_metadata	List valid dimensions and metrics
ga4_run_report	Historical GA4 reports
ga4_run_realtime_report	Last ~30 minutes

Local development

npm install
copy .env.example .env.local

Fill in .env.local, then:

npm run dev

• App: http://localhost:3000
• MCP: http://localhost:3000/ga4mcp
• Google OAuth: http://localhost:3000/oauth/google
• Health: http://localhost:3000/health

npm test
npm run build

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

Google Cloud setup (one project)

Use the same Google Cloud project for APIs, OAuth, and Cloud Run.

1. Install and sign in

1. Install the Google Cloud SDK.
2. Run:

gcloud auth login
gcloud auth application-default login

3. Create or select a project in Google Cloud Console.

gcloud config set project YOUR_PROJECT_ID

2. Enable APIs

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

This enables:

• Cloud Run
• Cloud Build
• Artifact Registry
• Google Analytics Data API
• Google Analytics Admin API

Or enable them in Console: APIs & Services → Library.

3. OAuth consent and web client

This Google OAuth client is only so Cloud Run can read your GA4 data. It is not the Claude.ai Advanced Settings client.

1. Open APIs & Services → OAuth consent screen.
2. User type: External for a personal Gmail account.
3. App name: GA4 MCP.
4. Add yourself as a test user if you stay in Testing.
5. Publish to Production so refresh tokens do not expire after 7 days.
6. Create OAuth client ID credentials.
7. Application type: Web application.
8. Authorized redirect URIs (add both):
   • http://localhost:3000/oauth/google/callback
   • https://ga4-mcp-XXXXXXXX-uc.a.run.app/oauth/google/callback
     (use the real Cloud Run URL after the first deploy)
9. Scope used by this app:

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

10. Copy the client ID and client secret. Do not commit them.

The Google account you authorize must already have access to the GA4 properties Claude should query.

Deploy to Cloud Run

Default service name: ga4-mcp. Default region: us-central1.

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

The script prints:

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

The service is deployed allow unauthenticated. That is required. Claude.ai connects from Anthropic (160.79.104.0/21). Auth is MCP_AUTH_TOKEN / MCP OAuth, not Cloud Run IAM.

Set environment variables

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

Then add the Cloud Run callback URL to the Google OAuth client if you have not already.

Connect Google

1. Open https://ga4-mcp-XXXXXXXX-uc.a.run.app/oauth/google
2. Enter MCP_AUTH_TOKEN
3. Sign in with your Google account
4. Copy GOOGLE_REFRESH_TOKEN from the success page
5. Set it and let Cloud Run start a new revision:

.\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 cannot write env vars from inside the container. Same rule as any serverless host.

Confirm the service

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

must return:

{"status":"ok"}

Environment variables

Variable	Required	Purpose
APP_BASE_URL	Yes	Cloud Run origin, no trailing slash
GOOGLE_CLIENT_ID	Yes	Google OAuth web client
GOOGLE_CLIENT_SECRET	Yes	Google OAuth web client secret
GOOGLE_REDIRECT_URI	No	Defaults to ${APP_BASE_URL}/oauth/google/callback
MCP_AUTH_TOKEN	Yes	Operator setup token for Google OAuth and Claude MCP consent
GOOGLE_REFRESH_TOKEN	After Google OAuth	Long-lived Google token
OAUTH_STATE_SECRET	No	Signs Google OAuth state cookies
MCP_TOKEN_SECRET	No	Signs MCP JWTs. Defaults to MCP_AUTH_TOKEN
MCP_OAUTH_CLIENT_ID	No	Only for Claude.ai Advanced Settings confidential client
MCP_OAUTH_CLIENT_SECRET	No	Pair for that optional client

Set these on the Cloud Run service. Do not put them in Git.

Optional Console path: Cloud Run → ga4-mcp → Edit & deploy new revision → Variables & secrets.

Claude.ai Custom Connector

1. Confirm /health returns {"status":"ok"}.
2. Finish Google OAuth and set GOOGLE_REFRESH_TOKEN.
3. In Claude.ai open Customize → Connectors → Add custom connector.
4. Name: GA4 Analytics
5. URL:

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

6. Leave Advanced OAuth Client ID / Secret empty.
7. Click Add.
8. Enable the connector in + → Connectors.
9. The first GA4 tool call shows Connect. Enter MCP_AUTH_TOKEN on this app’s consent page (not your Google password).
10. Ask: How many users did I have yesterday?

Manual gcloud (if you do not want the scripts)

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

Security

• Never log Google tokens, authorization codes, client secrets, or MCP JWTs.
• MCP tools never return secrets.
• Only GOOGLE_REFRESH_TOKEN is persisted, as a Cloud Run env var.
• Cloud Run ingress is public so Claude can connect. Do not also put a Cloud IAP / IAM login in front of /ga4mcp.
• Generate a long random MCP_AUTH_TOKEN.

Dates

Passed to GA4 unchanged: today, yesterday, 7daysAgo, 30daysAgo, 90daysAgo, or YYYY-MM-DD. The date dimension comes back as YYYYMMDD.

Known limitations

• One Google account and one refresh token.
• Cloud Run cannot persist a file or mutate env vars at runtime; set GOOGLE_REFRESH_TOKEN and deploy a new revision.
• Google Testing-mode refresh tokens expire after about 7 days.
• Realtime data is roughly the last 30 minutes.
• Report size is capped at 10,000 rows.
• Cold starts can add a few seconds when min-instances is 0.

Files added for Cloud Run

File	Purpose
Dockerfile	Production Next.js standalone image
cloudbuild.yaml	Build image and deploy Cloud Run
scripts/cloud-run-setup.ps1	Enable APIs and Artifact Registry
scripts/cloud-run-deploy.ps1	Build and deploy
scripts/cloud-run-set-env.ps1	Set Cloud Run env vars