Google Analytics MCP Server: Querying GA4 and BigQuery With AI Agents
Google’s open-source MCP server turns GA4 reports into tools that Claude, Cursor and other agents can call. Here is how to set it up safely, what it costs in quota, and where BigQuery takes over.
Google’s official Google Analytics MCP server reached version 1.0 on November 3, 2026, and version 1.1.0 followed three days later. The package now declares itself production-ready, and it can write three things to a GA4 property, annotations, custom dimensions and key events, but only behind an opt-in flag. Everything else it does is read-only. It lets an AI agent such as Claude, Cursor or Google’s Antigravity call the GA4 Admin API and Data API on your behalf, so you can ask a large language model a plain question about your data and get an answer built from a real report request instead of a guess. That grounding is what makes it useful for data-driven decisions.
The Google Analytics MCP server is a free, open-source program that runs on your own machine, signs in with your Google credentials, and turns GA4 reporting into tools an agent can call. It answers questions the GA4 reports can answer, within GA4 Data API quotas. It does not touch raw event data. For that, Google runs a separate remote BigQuery MCP server that can query your GA4 export. This post covers both, with the setup, the permissions I recommend, the quota math, and a checklist for trusting what the agent tells you.
What the Google Analytics MCP Server Actually Does
The server lives on GitHub under the googleanalytics organization and on PyPI as analytics-mcp. Google first released it in mid-2025 and kept an experimental label on it until version 1.0. By default your AI client starts it as a local process on your own machine. Since 1.0 you can also host it yourself as a multi-user HTTP service, where each person signs in with their own Google account, and the README includes a Dockerfile and a Cloud Run route for that. Google lists no hosted endpoint for it in its Google Analytics MCP setup guide, so there is still no URL to paste into a web chat.
In version 1.1.0, the agent gets ten read-only tools:
- get_account_summaries: every account and property the signed-in identity can see.
- get_property_details: configuration for one property, such as time zone and currency.
- list_google_ads_links: the Google Ads accounts linked to a property.
- list_property_annotations: the annotations already on a property.
- list_key_events: the key events defined on a property, formerly called conversions.
- get_custom_dimensions_and_metrics: the custom definitions, so the agent stops inventing field names.
- run_report: a standard Data API report with dimensions, metrics, filters, ordering and up to 250,000 rows per response.
- run_realtime_report: activity from the last 30 minutes (60 on Analytics 360).
- run_funnel_report: a funnel built from ordered steps, with optional breakdowns.
- run_conversions_report: attributed conversions, ad cost and return on ad spend, using data-driven or last-click attribution.
Three write tools appear only when you start the server with the allow-write flag: create_property_annotation, create_custom_dimension and create_key_event. Every tool carries MCP annotations that mark it read-only or not, so a client can tell the write tools apart from the rest.
Two of the reporting tools sit on alpha APIs. Funnel and conversions reports use the Data API v1alpha, and Google’s own documentation warns that conversion reporting may not be available for every property yet. If the agent hits an error on run_conversions_report, eligibility is the first thing to rule out. There is no pivot report tool and no batch tool, so a question that needs a cross-tab gets answered with several run_report calls.
How to Set Up the Google Analytics MCP Server
You need Python 3.10 or newer, a package runner (pipx or uv), a Google Cloud project, and the gcloud CLI.
- Enable the Google Analytics Admin API and the Google Analytics Data API in your Cloud project.
- In GA4 Admin, give the identity the agent will use at least the Viewer role on the property.
- Create Application Default Credentials with the analytics.readonly scope, either as yourself or by impersonating a service account.
- Add the server to your MCP client’s config with two environment variables: the absolute path to the credentials file and your Cloud project ID.
- Restart the client and ask it what the analytics server can do.
gcloud services enable analyticsadmin.googleapis.com analyticsdata.googleapis.com --project=YOUR_PROJECT_ID
gcloud auth application-default login \
--impersonate-service-account=ga-agent@YOUR_PROJECT_ID.iam.gserviceaccount.com \
--scopes="https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform"
gcloud auth application-default set-quota-project YOUR_PROJECT_ID
For Claude Desktop, the block below goes into claude_desktop_config.json. Claude Code takes the same values through claude mcp add, and Cursor reads an equivalent file at .cursor/mcp.json.
{
"mcpServers": {
"analytics-mcp": {
"command": "/opt/homebrew/bin/pipx",
"args": ["run", "analytics-mcp"],
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "/Users/you/.config/gcloud/application_default_credentials.json",
"GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"
}
}
}
}
Three details in that config head off most of the problems people raise in support threads. Use absolute paths everywhere, because many MCP hosts do not expand the tilde or $HOME inside JSON. Point the command at the full pipx or uvx binary, because desktop apps often start without your shell’s PATH. Set the quota project, because user credentials without one fail with ACCESS_NOT_CONFIGURED even when both APIs are enabled.
If you followed an older tutorial, note that Google’s guide now marks Gemini CLI as deprecated and points Antigravity users to a config file at ~/.gemini/config/mcp_config.json instead of the old settings.json.
Which GA4 Permissions Should the Agent Get
Treat the agent as a new junior analyst with a very fast keyboard. It should see only what it needs, and every number it reads should be one you would be comfortable seeing in a chat transcript.
The setup I recommend is a dedicated service account, impersonated through gcloud, with the Viewer role on the specific properties the agent works on. Google recommends a separate identity for agents on its Cloud MCP servers, and the reasoning carries over. You can revoke access in one place, and API activity is attributable to the agent rather than to you.
GA4 data restrictions apply here too. A property administrator can add No Cost Metrics or No Revenue Metrics to a user’s role, and Google states that the Analytics API enforces those restrictions just as the interface does. If the agent’s job is content or engagement analysis, there is no reason for it to see revenue, so restrict it.
Be careful with the credentials file. The documented login command requests the cloud-platform scope alongside analytics.readonly, so the file on disk can do more than the server ever asks of it. Keep it out of synced folders and repositories, and treat it like a password.
Leave writes off until you have a reason. Annotations are useful, since an agent that spots a tracking break can mark the date for everyone, but the flag needs the analytics.edit scope and a bigger role. The README asks for Editor to create a custom dimension and Marketer or Editor to create a key event, and every custom dimension uses up one of the property’s limited custom definition slots. That is a much bigger grant than Viewer for features that save you a few clicks.
GA4 Data API Quotas an AI Agent Can Burn Through
An agent does not ask one question. It calls get_custom_dimensions_and_metrics, tries a report, adjusts a filter, retries with another date range, and only then answers. Every one of those calls draws from the same property quota as your dashboards, scheduled exports and connectors.
For a standard GA4 property, the Data API allows 200,000 Core tokens per property per day and 40,000 per hour, with a cap of 14,000 tokens per hour for any single Cloud project on that property, and 10 concurrent requests. Analytics 360 properties get ten times those token allowances and 50 concurrent requests. Realtime and Funnel requests each draw on their own pool with the same limits. Daily quotas reset at midnight Pacific time, and hourly ones refill within the hour.
Most requests cost 10 tokens or fewer, which sounds generous. The cost climbs with long date ranges, many dimensions, complex filters and high-cardinality fields such as pagePath, and with the event volume of the property itself. When an agent pulls a year of landing pages by source on a busy ecommerce property, that request sits at the expensive end.
Three habits keep the agent inside its budget:
- Give the agent its own Cloud project. The 14,000-token hourly ceiling then applies to the agent alone, so a runaway session cannot use up the per-project allowance your other connectors depend on.
- Ask for quota status. All four report tools accept a return_property_quota argument, and the response then carries consumed and remaining token counts for the day and the hour. Tell the agent to include it while you learn its habits.
- Watch the thresholding allowance. A property gets 120 potentially thresholded requests per hour, and age, gender, interests and audience dimensions all count toward it.
When to Query BigQuery Instead of the Data API
The GA4 server answers report-shaped questions: totals, trends, channel splits, funnels, attributed conversions. Its numbers should match the GA4 interface, because they come from the same processed data and the same thresholding rules. It cannot answer questions that need individual events or users, such as the sequence of events before a refund, the share of purchasers who first arrived on a blog post, or which event parameters a broken tag stopped sending.
That is BigQuery territory. If the property exports to BigQuery, the raw events sit in a dataset named analytics_ followed by the property ID, in daily events_YYYYMMDD tables and, with streaming enabled, events_intraday_YYYYMMDD tables. Google’s BigQuery remote MCP server turns on as soon as you enable the BigQuery API and lives at https://bigquery.googleapis.com/mcp over Streamable HTTP, so web-based clients can reach it without anything running on your laptop.
A quick decision rule:
- The question matches a GA4 report or exploration: use the GA4 server.
- The answer must agree with what stakeholders see in GA4: use the GA4 server.
- The question needs user-level paths, raw event parameters, or joins with CRM or order data: use BigQuery.
- The question is about today and the property has no streaming export: use run_report with today as the date range for the processed part of the day, or the realtime tool for anything in the last 30 minutes.
The BigQuery server needs three IAM roles: MCP Tool User and BigQuery Job User on the project that runs the queries, and BigQuery Data Viewer for the data, which you can grant on the analytics dataset alone instead of the whole project. Its tools include execute_sql_readonly, which accepts only SELECT statements, and execute_sql, which accepts anything, including DROP TABLE. Google calls execute_sql the only tool that is not read-only and documents an IAM deny policy that blocks read-write MCP tool use. Apply it for any identity that only needs to read.
Its limits shape how you prompt it. Queries stop after three minutes by default, results cap at 3,000 rows, and every job carries the label goog-mcp-server: true, so you can find agent queries in your job history. Cost is the bigger risk. Custom quotas can cap the bytes processed per day for a project or for each user, though Google calls them approximate and they apply only to on-demand pricing. Put agent queries in their own project with a daily cap, and make date filters a habit:
SELECT event_name, COUNT(*) AS events
FROM `YOUR_PROJECT_ID.analytics_123456789.events_*`
WHERE _TABLE_SUFFIX BETWEEN '20261001' AND '20261031'
GROUP BY event_name
ORDER BY events DESC
The wildcard with a _TABLE_SUFFIX range keeps the scan to the days you name. An agent that writes events_* without it scans every day in the export.
Use Cases That Work for Analysts Today
The GA4 server earns its place on questions that are quick to ask and slow to click through. Good examples:
- Property audits: list every property you can access, its time zone, currency, Google Ads links and custom dimensions, then flag inconsistencies across a portfolio in one pass.
- Anomaly triage: when key events drop, ask for the same metric split by device, browser, country and landing page across the two weeks around the drop. The agent runs the splits faster than you can build them.
- Channel and campaign checks: compare data-driven and last-click conversions by channel group with run_conversions_report, where the property supports it.
- Funnel questions: build a checkout funnel on demand, broken down by device category.
- Annotation hygiene: with writes on, record known incidents such as tag releases or consent banner changes on the right dates.
It is weaker on scheduled reporting. A team KPI view that people check every morning belongs in a dashboard tool, like the one in this tutorial on real-time marketing dashboards in Databox, because a fixed view gives everyone the same number with the same definition. The agent is better for the follow-up question nobody built a chart for.
Both servers follow the same pattern. An agent that calls a reporting tool fetches live, structured numbers at the moment you ask, which is a different mechanism from retrieval augmented generation, where a model pulls in stored documents as text. MCP is one way to give an AI the connected, governed data access that turns it into the intelligence layer teams keep asking for, provided the data underneath is clean. For warehouse work, the export tables an agent would query through the BigQuery server are the same ones used to build an LTV dashboard from GA4 data in BigQuery.
How to Check an Agent’s GA4 Numbers Before Sharing Them
The agent’s answer is only as good as the request it built. A language model can pick a plausible but wrong field name, assume a date range you did not mean, or drop a filter without saying so. Five checks cover those failure points:
- Ask for the request. Have the agent show the exact dimensions, metrics, date ranges and filters it sent to run_report before it summarizes. A wrong field is far easier to spot in the request than in the prose answer.
- Check the date range and time zone. Relative dates such as yesterday resolve in the property’s time zone. Confirm the range matches what you meant, especially around month ends.
- Match one number against the GA4 interface. Pick the headline figure and open the same report in GA4 with the same dates and filters. They should agree, since both come from processed data.
- Watch for thresholding and missing rows. GA4 can withhold small segments for privacy, and demographic dimensions are the usual cause. A suspiciously round or empty result needs a second look.
- Label the source. Say whether a number came from the GA4 server or from BigQuery export tables, since the two are built differently and will not always agree.
Run those five on the first dozen answers before you let the agent’s numbers travel on their own. When a custom dimension keeps getting misread, give it a clearer name and description in GA4. The agent reads those definitions through get_custom_dimensions_and_metrics, and so does every new analyst on the team.



