v2.11.6 · MIT · local stdio · read-only
Ask GA4 a question. Get the answer an analyst would give.
One MCP server for Claude, Cursor, Codex, Gemini CLI and fourteen more clients. Twelve tools, sixteen analytical skills, and a schema check that validates every field name against your property before the query runs.
Install
curl -fsSL "https://ga4.builditwithai.xyz/install" | bashFinds your client, writes the entry, checks the credentials.
An agent with a GA4 tool guesses. That is the whole problem.
Three failures show up every time someone points a general-purpose model at the Analytics Data API.
It invents field names
Models are trained on Universal Analytics vocabulary. pageviews instead of screenPageViews. The API returns a 400 and the agent retries with another guess.
It invents a method
Ask why traffic dropped and it will produce a plausible five-step analysis that never checks whether the drop was one channel or all of them.
It does the arithmetic itself
Pull seven daily rows, ask for the week, and the model sums them in its head. Rates do not sum. The number is wrong and looks fine.
What this server does about it
Three mechanisms, all of them inside the tool call. Nothing here depends on the model behaving well.
Schema check before the query
get_ga4_data validates every dimension and metric name against your live property. A wrong name comes back with the reason and the correct spelling, not a 400 and a retry loop.
Skills loaded on demand
Sixteen recipes ship in the package — traffic diagnosis, ecommerce, attribution scope, AI referral split. The agent loads one before it analyzes, so the method is fixed instead of improvised.
Totals computed by GA4
Every multi-row pull returns a totals block that GA4 computed server-side. The model reads the period figure instead of adding up rows and drifting.
What it does when the setup is broken
Most failures are not analysis failures. They are a missing property ID, an expired token, or a service account that was never added to the property. The server handles all three inside the session.
Setup recovery mid-session
setup_ga4_access collects the missing value and reconnects without a restart. No client config editing, no reinstall.
Guides bundled offline
get_troubleshooting_guide serves the setup, IAM and schema fix paths from inside the package. It works with no network and no API access.
Row guard before the pull
Large queries are estimated first and warn above 2,500 rows, so one careless question does not fill the context window with raw rows.
Against Google's own server
Google ships an official Analytics MCP server, and it is genuinely good. Here is the honest split.
Google's Analytics MCP
- Admin API plus Data API: accounts, properties, Google Ads links, core and funnel reports, realtime.
- Hosted remote endpoint at
analyticsdata.googleapis.com/mcp/v1— no local install at all. - Apache-2.0, labelled Experimental, maintained by the Analytics organisation.
- Best choice when you want zero install and a vendor-maintained toolset.
This server
- Reporting and metadata, with the analysis layer attached: 16 skills, schema validation, GA4-computed totals, row guard.
- Local stdio over your own credentials. Nothing leaves your machine except GA4 API calls.
- MIT, one maintainer, and a fix path for the three errors that actually stop people.
- Best choice when the agent has to reason about the numbers, not just fetch them.
Natural language analytics & production prompts
Query your analytics data directly from conversation without memorising API dimension names or building filter JSON by hand.
How natural language GA4 works
Why raw models hallucinate Universal Analytics metrics, how the MCP schema layer bridges the vocabulary gap, and why local stdio keeps company traffic numbers private.
35 copy-paste analytical prompts
Production prompts for traffic diagnosis, ecommerce funnels, AI referral tracking, content audits, and bot traffic detection across Claude, Cursor, and Gemini.
Sixteen skills, loaded only when needed
Each one is a short playbook with the exact dimensions, metrics and interpretation rules for one job. The agent calls search_skills, gets one back, and follows it.
| Skill | What it settles |
|---|---|
| Traffic diagnosis | Whether a change is real, and which channel moved first |
| Ecommerce | Revenue, conversion rate, AOV and funnel drop-off |
| AI referrals | Splitting ChatGPT, Claude, Perplexity and Gemini traffic from organic |
| Attribution scope | Why session, event and user numbers never match |
| Metric names | The GA4 name for the UA name the model guessed |
| All sixteen | Including filters, date ranges, custom dimensions, bot traffic |
Your client is on the list
The installer writes the entry for eight of them. Codex, Gemini CLI, Goose and Kiro take one config block each, quoted from that vendor's own documentation.
Auto-configured
Claude Desktop and Code, Cursor, VS Code (Cline, Roo Code), Continue.dev, OpenCode, Devin Desktop (formerly Windsurf), Zed, Google Antigravity.
One block, copied from the vendor
Codex writes TOML, Goose writes YAML, Gemini CLI and Kiro write JSON. Each guide shows the exact shape that client expects.
Start here
The client hub has every guide, or go straight to Claude or Cursor.
Install
Run the installer
curl -fsSL "https://ga4.builditwithai.xyz/install" | bashIt detects your client, checks for
uv, and writes the server entry. Restart the client afterwards.Give it two values
export GA4_PROPERTY_ID="123456789" export GOOGLE_APPLICATION_CREDENTIALS="/absolute/path/to/key.json"Both live inside the client's server entry. The property ID is the numeric one from Admin, Property details — not the
G-measurement ID.Ask a question that needs a real answer
Why did organic sessions drop in the last 7 days?You have succeeded when the agent loads the
traffic-diagnosisskill and callsget_ga4_datawithout a setup error. Full setup guide.
The parts people get stuck on
Error triage & fixes
Step-by-step triage for 403 permission denied, 400 invalid field names, 429 quota limits, and scope errors.
The 403 that is not a bug
The service account is valid but was never added to the property. Nine steps in the Analytics UI, with the exact role.
The filter shape
dimension_filter follows the Data API v1beta schema, not SQL. Working templates for string, list, numeric and AND/OR groups.