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

Related MCP server: GA4 MCP Server

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

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