# Google Analytics 4 MCP: an MCP server by Scalably

Canonical: https://scalably.io/mcp/ga4-mcp
Source: https://github.com/scalably-io/ga4-mcp
Registry: https://registry.modelcontextprotocol.io/v0.1/servers/io.scalably%2Fga4-mcp/versions/1.0.1
Provenance: derived from `container/tools/ga4-mcp/server.py` at `3122d1c8` (2026-08-31) in the private ScalablyAI repository
Integrity: sha256 of the raw README served at https://scalably.io/mcp/ga4-mcp.md is d17ba0d43013b165e1024f4f482854dff66dd2263118c949c092f2a7a5634080. Verify: curl -s https://scalably.io/mcp/ga4-mcp.md | shasum -a 256
This is the machine-readable representation of the page at the canonical URL. Same facts, denser format.

## Direct answer
Google Analytics 4 MCP: reports, realtime, funnels, pivots, metadata, admin lists. 17 tools.

GA4 reports, realtime and funnels behind our content and ads reporting.

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

## Environment
| Variable | Required | Secret | Purpose |
|---|---|---|---|
| `GOOGLE_APPLICATION_CREDENTIALS` | yes | no | Path to a Google service-account JSON file with the analytics.readonly scope; add the service account as a Viewer on each GA4 property |
| `GA4_LOG_LEVEL` | no | no | Log level, default INFO |

## Tools
| Tool | Description |
|---|---|
| `ga4_list_account_summaries` | List every GA4 account and its child properties accessible to this service account |
| `ga4_get_property_details` | Full metadata for a single GA4 property |
| `ga4_list_data_streams` | List all data streams (web, iOS, Android) on a GA4 property |
| `ga4_list_custom_dimensions` | List custom dimensions configured on a GA4 property |
| `ga4_list_custom_metrics` | List custom metrics configured on a GA4 property |
| `ga4_list_key_events` | List key events (formerly conversions) on a GA4 property |
| `ga4_list_audiences` | List audiences defined on a GA4 property |
| `ga4_list_google_ads_links` | List Google Ads links attached to a GA4 property |
| `ga4_list_property_annotations` | List reporting annotations on a GA4 property |
| `ga4_run_access_report` | Audit log of who read what on a GA4 property, last 12 months |
| `ga4_get_metadata` | Fetch the full GA4 dimension and metric catalog for a property |
| `ga4_run_report` | Run a GA4 standard report, the workhorse tool |
| `ga4_batch_run_reports` | Run up to 5 GA4 reports in a single round trip |
| `ga4_run_pivot_report` | Run a GA4 pivot report |
| `ga4_run_realtime_report` | Run a GA4 real-time report covering the last 30 minutes |
| `ga4_check_compatibility` | Validate whether a dimension and metric combo can be queried together |
| `ga4_run_funnel_report` | Run a GA4 funnel report (v1alpha, drop-off analysis) |

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

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

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

## Reliability
- CI: https://github.com/scalably-io/ga4-mcp/actions/workflows/validate.yml
- Release 1.0.1
- Verified 2026-08-31
- Each of ours started as an internal ScalablyAI MCP server. We stripped the internal envelope, the auth wrapper and client dispatch that only make sense inside our own platform, and kept the tool surface. Every release runs through a clean-install CI job, publishes under the io.scalably namespace with trusted publishing so no long-lived token ever leaves our CI, and registers on the official MCP registry.

## Related
- Read more: [AI agents for SEO: 5,329 tasks at 98% over four months](https://scalably.io/blog/ai-agents-for-seo), [How to build an MCP server in Python (production guide)](https://scalably.io/blog/how-to-build-mcp-server-python), [What is an MCP server? A clear explainer for developers](https://scalably.io/blog/what-is-an-mcp-server)