Model Context Protocol · GA4 Data API v1beta

GA4 MCP Server

Google Analytics 4 for AI agents.

Point Claude, Cursor, or any MCP client at your GA4 property. The server reads your property's real schema before it writes a query, asks GA4 for period totals instead of letting the model sum rows, and keeps 15 analytical skills one call away.

Install in one line Read the setup guide

v2.11.4 · MIT · PyPI + npm + one-line installer · Not affiliated with Google

On this page: Install · Clients · Why · Compare · Quick start · FAQ

Install

Three ways in. The installer finds your client and writes the config entry; the runtime commands drop into any MCP client's config.

# Universal installer (auto-configures your client)
curl -fsSL "https://ga4.builditwithai.xyz/install" | bash

Detects Claude Desktop, Claude Code, Cursor, VS Code (Cline, Roo Code), Continue.dev, Windsurf, Zed, Google Antigravity, and OpenCode.

# uvx
uvx google-analytics-mcp

Requires uv.

# npx
npx -y @surendranb/google-analytics-mcp

The npm package launches the Python server through uvx, so uv is required here too.

# Claude Code users
claude mcp add google-analytics -- uvx google-analytics-mcp

Adds the server to Claude Code in one command.

Before the first query, set two env values: GA4_PROPERTY_ID and GOOGLE_APPLICATION_CREDENTIALS. Both are covered in quick start below. No installer run is required for the runtime commands; they fetch the package on first launch.

Works with your client

No hand-edited JSON needed for most setups.

Claude Code
Claude Desktop
Claude Cowork
OpenAI Codex
Google Antigravity
Cursor
OpenCode
VS Code (Cline, Roo Code)
Continue.dev
Windsurf
Zed
Gemini CLI (extension in the repo)

The server speaks MCP over stdio. The installer auto-configures Claude Desktop, Claude Code, Cursor, VS Code (Cline, Roo Code), Continue.dev, OpenCode, Windsurf, Zed, and Google Antigravity. Any client that can launch a local MCP server works with a standard stdio config.

Why this server

Field names checked against your property
search_schema and the category browsers read a schema fetched from your own GA4 property at boot. get_ga4_data checks every dimension and metric before the API call, so an invalid name comes back with the fix instead of a raw 400.
15 analytical skills, loaded on request
Traffic drops, channel acquisition, ecommerce, AI referrals, bot detection, field-name maps. Skills are fetched from the repo when asked, so adding one doesn't need a package release.
Totals computed by GA4, not your model
Multi-row pulls return a totals block from GA4's own aggregation, plus a note telling the agent to read the period figure there instead of summing rows itself.
Defaults that stop runaway queries
Row counts are estimated before the fetch by default. A query that would return more than 2,500 rows comes back with a warning and concrete ways to narrow it, unless you pass proceed_with_large_dataset=True. Common metric aliases (conversions → keyEvents) and filter-shape repairs fix the mistakes models actually make.
The boring failures have built-in fixes
Setup, IAM, and schema guides ship inside the package and work offline. On clients that support prompts, setup_ga4_access collects a missing property ID or credentials path mid-session and reconnects without a restart.
Telemetry you can switch off
Anonymous diagnostics only: no queries, no credentials, no analytics data. Set DISABLE_TELEMETRY=1 or DO_NOT_TRACK=1 and the server stops sending, and stops writing its local ID file. MIT licensed, no account.

This server vs Google's official Analytics MCP server

Both servers are real, and both are free to use. Google publishes its own Analytics MCP server (labeled experimental, Apache-2.0). This one is community-built and MIT-licensed. Here's the split, without the sales gloss.

Feature comparison between this GA4 MCP server and Google's Analytics MCP server
	This server	Google's server (google-analytics-mcp)
Built by	Community project by Surendran B (BuildItWithAI); not affiliated with Google	Google's Analytics organization
Status	v2.11.4, MIT	Labeled "Experimental", Apache-2.0
API coverage	GA4 Data API: reporting + metadata	Admin API + Data API: account and property info, Google Ads links, core, funnel, and realtime reports
Setup	One-line installer, or uvx / npx; property ID + credentials	pipx run analytics-mcp; requires a Google Cloud project ID and enabling the Admin + Data APIs
Extras	15 skills loaded at call time, pre-flight schema checks, GA4-computed totals, row-cap guard, offline troubleshooting guides, in-session setup recovery	Vendor-maintained reference toolset

When to use which

Reach for Google's server if you want the vendor-maintained baseline, funnel reports, or Google Ads account links.

Reach for this one if you're driving an agent through day-to-day analysis and want it to stop guessing field names, read period totals instead of summing rows, and follow a documented method per question.

GA4 MCP is an independent open-source project. It isn't affiliated with, endorsed by, or sponsored by Google. "Google Analytics" is a trademark of Google LLC.

Quick start

1. Get credentials and a property ID

Two options, both local to your machine.

Service account (recommended for a persistent setup): create a service account in Google Cloud Console, download its JSON key, then add the service account's client_email as a Viewer on your GA4 property (Admin → Property Access Management).

gcloud: run gcloud auth application-default login and use the generated credentials file. Then set both values:

export GA4_PROPERTY_ID="123456789"                      # numeric ID, Admin → Property details
export GOOGLE_APPLICATION_CREDENTIALS="/absolute/path/to/key.json"

Your property ID is the numeric one, not the G- measurement ID.

2. Install and wire your client

curl -fsSL "https://ga4.builditwithai.xyz/install" | bash

The installer detects your client and writes the config. Prefer manual? Add uvx google-analytics-mcp to your MCP config and pass the two env values above.

3. Ask your first question

"What were my top channels last week?" · "Why did organic traffic drop in the last 7 days?" · "How much traffic came from AI assistants?" The agent picks the dimensions and metrics, runs the report, and reads the totals GA4 computed.

Install now

FAQ

What is MCP?

Model Context Protocol is a standard for connecting AI apps to external tools. Your client launches this server, and the agent gets GA4 querying tools: reporting, schema search, skills, and troubleshooting.

Does it work with Claude? What about ChatGPT?

Claude Code, Claude Desktop, and Claude Cowork all run this server. The installer covers Claude Desktop and Claude Code; Cowork is Claude Desktop's local agent mode, and local MCP servers run through the desktop app. OpenAI's Codex CLI connects and is in regular use with this server; the ChatGPT app can't launch local stdio servers, so it can't connect to this one.

Service account or OAuth?

Both patterns run locally. A service-account JSON key doesn't expire and suits fixed or shared setups. Google Application Default Credentials via gcloud auth application-default login use OAuth user credentials refreshed on your machine. The quick start uses a service account because it has the fewest moving parts.

Is it free?

Yes. MIT licensed, no account, no seat pricing, no hosted service in the query path. Queries run from your machine straight to Google's GA4 Data API, and your use of Google's APIs is governed by Google's terms and quotas.

What does it collect, and can I turn telemetry off?

Anonymous usage diagnostics: which tools ran, latency, error codes. No queries, no credentials, no analytics data, no file paths. Set DISABLE_TELEMETRY=1 or DO_NOT_TRACK=1 and nothing is sent; when opted out, the server also stops creating its local ID file. The privacy policy has the full detail.

How many tools does it ship?

11 in v2.11.4: get_ga4_data for reports, six schema tools for field discovery (search, full schema, and category browsing), plus list_properties, search_skills, get_troubleshooting_guide, and setup_ga4_access.

Is there an official Google Analytics MCP server?

Yes — Google ships an official Google Analytics MCP server (experimental, Apache-2.0), maintained by Google's Analytics organization, with coverage that includes funnel reports and Google Ads links. This one focuses on agent workflow: schema checks before a query runs, 15 skills on call, GA4-computed totals, and guided setup recovery. The comparison above has the full split.

Does it support Universal Analytics?

No. UA properties stopped processing data on 2023-07-01, and this server talks to GA4 only. If you're translating old field names, the ua-to-ga4 skill maps every common one.

Is it read-only?

Yes. Every tool is annotated read-only, and the server reads metadata and reports from the GA4 Data API. It doesn't change your GA4 configuration.

I'm getting an error. Where do I start?

Ask your agent to run get_troubleshooting_guide(topic="setup"), ("iam"), or ("schema"). The guides are bundled with the package and work offline. setup_ga4_access walks the fix mid-session, and this site's setup, IAM, and schema pages mirror the same steps.

Install GA4 MCP

For agents

Every page here has a markdown twin, and the browser exposes five read-only tools through navigator.modelContext when the client supports WebMCP. If you are an agent reading the HTML, the faster path is llms.txt for the map and llms-full.txt for every page in one file. Machine data: tools.json (11 tools), skills.json (15 skills).