Google Analytics 4 MCP

Read-only MCP server for Google Analytics 4. Seventeen tools cover the read surface of both the Data API and the Admin API: standard, batch, pivot, realtime and funnel reports; the metadata catalog and compatibility check; and admin lists for properties, streams, custom dimensions and metrics, key events, audiences, Google Ads links, annotations and access reports. We run this server in production for every analytics client.

Install

Claude Code:

claude mcp add ga4 -e GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json -- uvx scalably-ga4-mcp

Codex:

codex mcp add ga4 --env GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json -- uvx scalably-ga4-mcp

Claude Desktop: download ga4-mcp.mcpb from the latest GitHub release and open it.

Setup

1. In Google Cloud, create or pick a project and enable the Google Analytics Data API and the Google Analytics Admin API on it (APIs and Services, Library).
2. Create a service account in that project and download its JSON key.
3. Add the service account's email as a Viewer on each GA4 property you want to query (Admin, Property access management).

No OAuth consent screen is needed; the server authenticates as the service account with the analytics.readonly scope. One service account can read any property that grants it access, so there is no per-client configuration beyond step 3 above.

Call ga4_list_account_summaries first to discover which property_id values the service account can see, then pass one into the reporting or admin tools.

Tools (17)

Configuration

Filter expression shape

Every tool accepting dimension_filter / metric_filter takes a dict:

{"filter": {"field_name": "country", "string_filter": {"value": "US"}}}

Compose with boolean groups:

{"and_group": {"expressions": [
  {"filter": {"field_name": "country", "string_filter": {"value": "US"}}},
  {"filter": {"field_name": "deviceCategory", "string_filter": {"value": "mobile"}}}
]}}

A raw {"field_name": ..., "string_filter": ...} is auto-wrapped into {"filter": {...}}.

Reply shape

Every tool returns JSON with status (succeeded, partial, no_op), operation, summary, target, result, proof, warnings, recovery. Failures surface as a tool error whose text is ga4_request_failed: <message> <hint>. proof.nextOffset on a partial status means: continue from that offset. proof.propertyQuota carries the property's remaining Data API quota so the caller can self-throttle. proof.dataQualityLimited is true when the response was sampled, thresholded, or collapsed high-cardinality rows into (other); treat such a result as directionally useful, not exact.

Limits

250,000 rows per Data API response (the server caps any higher client-supplied limit). Batch reports: up to 5 per call. Funnel reports: up to 10 steps. Realtime reports use a separate, smaller dimension and metric catalog covering only the last 30 minutes; non-realtime data typically lags 24 to 48 hours. Funnel reporting is v1alpha and its shape can change upstream. Every quota bucket (core reports, realtime, funnel) allows roughly 14,000 quota tokens per project per property per hour (a complex query can cost more than one token); 360 properties get a 10x multiplier. Re-check Google's current quota page before relying on an exact number.

Verify

Each release lists the package version, the .mcpb sha256 and the production commit it was derived from in CHANGELOG.md. CI runs the tests and a clean install of the built wheel on every push.

Privacy Policy

This server runs locally, on your machine, under your own credentials. It collects no personal data, contains no telemetry, stores nothing persistently, and talks only to the vendor API it wraps. No third party, including Scalably, receives your data. Contact: hello@scalably.io. Canonical copy: https://scalably.io/connector-privacy.html

License

MIT. Copyright Scalably.