--- title: "Google Analytics MCP 1.0: what it does and how to connect it to GA4" description: "The official Google Analytics MCP server is now stable. Which reports it supports, how to install it with Claude or Cursor and why to start in read-only mode." url: "https://cookingmetrics.com/blog/mcp-google-analytics-ga4/" markdown_url: "https://cookingmetrics.com/blog/mcp-google-analytics-ga4.md" lang: "en" date_published: "2026-11-12" author: "Martín Garay" author_url: "https://cookingmetrics.com/about-martin-garay/" publisher: "CookingMetrics" publisher_url: "https://cookingmetrics.com/" keywords: ["MCP", "Google Analytics"] citation_apa7: "Garay, M. (2026, November 12). *Google Analytics MCP 1.0: what it does and how to connect it to GA4*. CookingMetrics. https://cookingmetrics.com/blog/mcp-google-analytics-ga4/" references_apa7: - "Google Analytics, GitHub. (n.d.). *Google Analytics MCP server*. https://github.com/googleanalytics/google-analytics-mcp" - "Google Analytics, GitHub. (n.d.). *Google Analytics MCP server: releases*. https://github.com/googleanalytics/google-analytics-mcp/releases" - "Google for Developers. (n.d.). *Google Analytics MCP server*. https://developers.google.com/analytics/devguides/MCP" - "Google Cloud. (n.d.). *Set up ADC for a local development environment*. https://docs.cloud.google.com/docs/authentication/set-up-adc-local-dev-environment" - "Python Packaging Authority. (n.d.). *pipx documentation*. https://pipx.pypa.io/" - "Google Analytics for Developers. (n.d.). *Google Analytics Data API basics*. https://developers.google.com/analytics/devguides/reporting/data/v1/basics" - "Google Analytics for Developers. (n.d.). *Google Analytics Data API schema*. https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema" --- # Google Analytics MCP 1.0: what it does and how to connect it to GA4 > The official Google Analytics MCP server is now stable. Which reports it supports, how to install it with Claude or Cursor and why to start in read-only mode. - **Author:** [Martín Garay](https://cookingmetrics.com/about-martin-garay/) · Founder of CookingMetrics - **Published:** November 12, 2026 - **Topics:** MCP, Google Analytics - **Web version:** https://cookingmetrics.com/blog/mcp-google-analytics-ga4/ ## How to cite this article (APA, 7th edition) Garay, M. (2026, November 12). *Google Analytics MCP 1.0: what it does and how to connect it to GA4*. CookingMetrics. https://cookingmetrics.com/blog/mcp-google-analytics-ga4/ In-text citation: (Garay, 2026) ## References - Google Analytics, GitHub. (n.d.). *Google Analytics MCP server*. https://github.com/googleanalytics/google-analytics-mcp In-text citation: (Google Analytics, GitHub, n.d.) - Google Analytics, GitHub. (n.d.). *Google Analytics MCP server: releases*. https://github.com/googleanalytics/google-analytics-mcp/releases In-text citation: (Google Analytics, GitHub, n.d.) - Google for Developers. (n.d.). *Google Analytics MCP server*. https://developers.google.com/analytics/devguides/MCP In-text citation: (Google for Developers, n.d.) - Google Cloud. (n.d.). *Set up ADC for a local development environment*. https://docs.cloud.google.com/docs/authentication/set-up-adc-local-dev-environment In-text citation: (Google Cloud, n.d.) - Python Packaging Authority. (n.d.). *pipx documentation*. https://pipx.pypa.io/ In-text citation: (Python Packaging Authority, n.d.) - Google Analytics for Developers. (n.d.). *Google Analytics Data API basics*. https://developers.google.com/analytics/devguides/reporting/data/v1/basics In-text citation: (Google Analytics for Developers, n.d.) - Google Analytics for Developers. (n.d.). *Google Analytics Data API schema*. https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema In-text citation: (Google Analytics for Developers, n.d.) --- **The Google Analytics MCP server is the official way for an AI assistant, such as Claude or Cursor, to query the data of a GA4 property through Google's APIs.** On November 3, 2026, Google released version 1.0.0 and the project left its experimental stage. Three days later, version 1.1.0 added the optional creation of key events and custom dimensions. This article explains which tools it includes, how to install it step by step and which precautions to take before enabling write access. Everything stated about how the server works comes from the [official GitHub repository](https://github.com/googleanalytics/google-analytics-mcp) and the [Google for Developers documentation](https://developers.google.com/analytics/devguides/MCP), both consulted on November 11, 2026. ## In summary - With 1.0.0 (November 3, 2026), the project is no longer experimental. The current version as of November 11, 2026 is 1.1.0. - It offers four reports (standard, realtime, funnel and conversions) plus configuration reads: accounts, property, key events, custom dimensions and metrics, Google Ads links and annotations. - Each report response returns up to 250,000 rows; larger volumes are paginated. - It is read-only by default. Creating annotations, key events or custom dimensions requires enabling `--allow-write`, adding the `analytics.edit` scope and holding the right role on the property. - It requires a Google Cloud project with two APIs enabled, credentials and Python 3.10 or later. ## What an MCP server is and what changes with version 1.0 MCP (*Model Context Protocol*) is an open protocol that lets an AI assistant use external tools. An MCP server exposes those tools with a name, a description and their parameters, and the assistant decides when to call them. Here, the tools query the Google Analytics Data API and the Google Analytics Admin API with the user's credentials. In practice, instead of building a report in the interface or writing code against the API, the question goes to the assistant, which turns the request into a query, runs it and returns the result. The project was released as an experiment in August 2025 (version 0.1.0). Version 1.0.0, from November 3, 2026, declares it stable, according to the [repository's release list](https://github.com/googleanalytics/google-analytics-mcp/releases). Version 1.1.0, from November 6, added minute ranges to realtime reports and the optional write tools for custom dimensions and key events. ## What it can do today ### Reports - **Standard report (`run_report`).** Dimensions, metrics, filters, ordering and date ranges. Each response returns up to 250,000 rows and can be paginated. - **Realtime (`run_realtime_report`).** The last 30 minutes, or up to two minute ranges within that window. Useful to confirm that a campaign launched minutes ago or a fixed tag is already sending data. - **Funnels (`run_funnel_report`).** User-defined steps, a breakdown by one dimension, segments and "next action" analysis: what people do after completing or abandoning the funnel. It uses the alpha version of the Data API, so it may change. - **Conversions (`run_conversions_report`).** Ad costs, conversions, return on ad spend (ROAS) and attribution model, data-driven (`DATA_DRIVEN`) or last click (`LAST_CLICK`). [Section for signed-in readers, level C: https://cookingmetrics.com/blog/mcp-google-analytics-ga4/#bloque-1] ### Configuration audit - Summary of the accounts and properties the credential can access. - Property details. - List of key events. - Custom dimensions and metrics. - Linked Google Ads accounts. - Property annotations. For an audit, this part is as useful as the reports: it makes it possible to ask, for example, which events are marked as key events and whether any of them recorded no activity in the last 30 days. [Section for signed-in readers, level C: https://cookingmetrics.com/blog/mcp-google-analytics-ga4/#bloque-2] ### Configuration (only with write access enabled) - Create annotations on the property timeline. - Create custom dimensions (requires the Editor role). - Mark an event as a key event (requires the Marketer or Editor role). These three tools are not available unless the server starts with write access enabled. ## Prerequisites - A Google Cloud project. - The Google Analytics Admin API and the Google Analytics Data API enabled in that project. - Access to the property with at least the Viewer role. - Credentials with the `https://www.googleapis.com/auth/analytics.readonly` scope. To write, `https://www.googleapis.com/auth/analytics.edit` as well. - Python 3.10 or later and `pipx` (or `uv`) to run the `analytics-mcp` package. ## How to install it step by step 1. **Enable the APIs.** From the Google Cloud console or with the Google Cloud CLI: ``` gcloud services enable analyticsadmin.googleapis.com analyticsdata.googleapis.com --project=YOUR_PROJECT_ID ``` 2. **Set up credentials.** The most direct option is Application Default Credentials (ADC): ``` gcloud auth application-default login --scopes="https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform" ``` The command reports the path of the credentials file it creates. Alternatively, a service account can be used, through impersonation or with a key file, and granted access to the property like any user. 3. **Add the server to the assistant.** In Claude Code: ``` claude mcp add analytics-mcp --scope user -e GOOGLE_APPLICATION_CREDENTIALS="PATH_TO_CREDENTIALS_JSON" -e GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" -- pipx run analytics-mcp ``` In Claude Desktop, Cursor or other compatible clients, the equivalent JSON configuration is: ``` { "mcpServers": { "analytics-mcp": { "command": "pipx", "args": ["run", "analytics-mcp"], "env": { "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON", "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID" } } } } ``` 4. **Test the connection.** Restart the client and ask something low-risk, for example: "Which Google Analytics accounts and properties can I access?" If the answer lists the expected properties, the connection works. The repository also documents running it as a self-hosted HTTP server, including on Cloud Run, with built-in OAuth. Google does not offer a hosted server: each team runs its own. [Section for signed-in readers, level C: https://cookingmetrics.com/blog/mcp-google-analytics-ga4/#bloque-3] ## Prompts to start with - "Compare sessions and key events from Meta against Google Ads for the last 30 days versus the previous period." The result depends on how Meta traffic is tagged: without consistent UTM parameters, part of that traffic may appear as referral or direct. - "Show the purchase funnel for paid traffic only. At which step do most people drop off, and what do they do next?" The assistant has to define a paid-traffic segment; ask it to state the condition it used. - "Is traffic from the campaign launched today arriving in realtime?" - "Add an annotation dated today: the bidding strategy was changed to target ROAS." This only works with write access enabled. In every case, ask the assistant to show the dimensions, metrics, filters and dates it used. A correct report built on the wrong definition is still a mistake. [Section for signed-in readers, level C: https://cookingmetrics.com/blog/mcp-google-analytics-ga4/#bloque-4] ## Why start in read-only mode Write access is enabled on purpose, with the `--allow-write` option or the `ANALYTICS_MCP_ALLOW_WRITE` environment variable, and it also requires the `analytics.edit` scope. Keeping it off at first has three advantages: - **Limited damage.** An ambiguous request cannot create key events or dimensions. A key event changes what reports count as a conversion and, if the property is linked, what may reach Google Ads. - **Limited quotas.** Properties have a maximum number of custom dimensions. A test dimension uses up a slot. - **Process.** Before delegating changes to an assistant, the team needs to define who approves them and how they are recorded. When write access becomes necessary, use a separate credential, limited to the relevant properties, and start with annotations, which do not alter the data. [Section for signed-in readers, level C: https://cookingmetrics.com/blog/mcp-google-analytics-ga4/#bloque-5] ## Limitations to keep in mind - **Misaligned documentation.** As of November 11, 2026, the Google for Developers page states that the server is available for read requests only and lists nine tools; the repository, at version 1.1.0, includes thirteen, three of them optional write tools. - **Alpha features.** Funnels and annotations rely on alpha versions of Google's APIs, which may change. - **Quotas.** Queries consume the project's Data API quota. Many chained questions over wide date ranges can exhaust it. - **Interpretation.** The server returns data; the assistant builds the conclusion. Figures should be checked before they are used in a decision or a client report. The assistant's answers are only as good as the property's configuration. If events, conversions or campaign attribution are not well defined, the [CookingMetrics Google Analytics self-check](https://cookingmetrics.com/google-analytics-self-check/) helps review them before relying on an automated query. ## Related reading - [Google Ads MCP: setup, eCommerce and B2B leads](https://cookingmetrics.com/blog/mcp-google-ads/), the equivalent server for the ad account. - [What we learned from reviewing our site for AI agents](https://cookingmetrics.com/blog/medimos-nuestro-sitio-agent-ready/), on how [CookingMetrics](https://cookingmetrics.com/) prepared its site for agents. ## Frequently asked questions ### Does the Google Analytics MCP change the property? No, unless write access is explicitly enabled. By default it only reads reports and configuration. With `--allow-write` and the `analytics.edit` scope it can create annotations, key events and custom dimensions, depending on the credential's role on the property. ### Do you need to code to use it? Not to query it: questions are asked in natural language. Installation does require working with the Google Cloud console, the command line and the AI client's configuration file. ### Does Google offer a hosted server? No. The server runs on the user's machine or on the team's own infrastructure, such as Cloud Run. The repository documents both options. --- ## About the author **[Martín Garay](https://cookingmetrics.com/about-martin-garay/)** — Founder of CookingMetrics I'm Martín Garay, founder and Martech Advisor at CookingMetrics and Chair of the Technology Committee at CACE, Argentina's ecommerce chamber. For more than 20 years I've worked in Analytics, development, technical SEO and ecommerce: I implement measurement, find where it breaks and turn it into information you can act on. ### My work at CACE, Argentina's ecommerce chamber - **Chair of the Technology Committee** (SINCE AUGUST 2025): I set the committee's agenda together with Gabriel Topola, vice-chair. We look at the platforms and tools an online business needs to grow: CMS, integrations, customer service and omnichannel operations. - **Curating the technical forum** (IT CAMP · ECOMMERCE DAY ARGENTINA): With CACE's Events team I put together the IT Camp programme: talks for engineering and development teams on platform architecture, code and good practice, given by speakers who do the implementation work. - **Marketing and Data Analytics committees** (SINCE 2016): I started in the Marketing committee and helped create the Data Analytics committee. I gave Google Analytics webinars, including the migration to GA4, and worked on the Google Analytics implementation for Hot Sale and Cyber Monday. - **Ecommerce metrics dashboard** (FOR MEMBERS): With the Data Analytics committee and the CACE Community team we built a dashboard in Google Analytics and Looker Studio so each member can check the key indicators of their own store. ### Talks - [From SEO to GEO: what it takes for a brand to be cited by an answer engine](https://www.youtube.com/watch?v=mlyjuSBdMzI) — ECOMMERCE DAY ARGENTINA 2026 · IT CAMP · AUGUST 27, 2026 · BUENOS AIRES CONVENTION CENTER - [SEO for AI: how to prepare a brand to show up in ChatGPT and Google's AI overviews](https://www.youtube.com/watch?v=4dI7jqnLg-M) — AI IN LATAM 2025 · BUENOS AIRES · OVER 3,500 ATTENDEES AND 100 SPEAKERS, PER THE ORGANIZERS ### Profiles and links - [Full profile](https://cookingmetrics.com/about-martin-garay/) - [LinkedIn](https://www.linkedin.com/in/seospecialistmartingaray/) - [Instagram](https://www.instagram.com/garaymartin/) - [YouTube](https://www.youtube.com/@MartinGaray) - [martingaray.com.ar](https://www.martingaray.com.ar/) - [Chair of the Technology Committee at CACE, Argentina's ecommerce chamber](https://cace.org.ar/pages/comision-de-tecnologia?utm_source=cookingmetrics.com&utm_medium=referral&utm_campaign=perfil-martin&utm_content=caja-autor) - [Ecommerce metrics dashboard, free for CACE members](https://cace.org.ar/pages/dashboard-de-metricas?utm_source=cookingmetrics.com&utm_medium=referral&utm_campaign=perfil-martin&utm_content=caja-autor) --- ## About CookingMetrics CookingMetrics provides Google Analytics consulting, measurement implementation and SEO. Founder Martín Garay brings more than 20 years of experience in Analytics, development and ecommerce. The work connects data with business decisions. ### Services - **[Google Analytics audit](https://cookingmetrics.com/data-analytics-consulting/)**: Do purchases or revenue differ from your store? We review your measurement and deliver a correction plan in 10 business days. [See the audit scope](https://cookingmetrics.com/data-analytics-consulting/). - **[Google Tag Manager](https://cookingmetrics.com/services/gtm/)**: Did events stop being tracked after a website change? We review tags, triggers and versions to find duplicates or missing data. [Ask about Google Tag Manager audits and implementation](https://cookingmetrics.com/services/gtm/). - **[Server-side measurement](https://cookingmetrics.com/services/cookieless-tracking/)**: We assess how to send data from your server, respect consent and prevent duplication. [What's included in server-side measurement](https://cookingmetrics.com/services/cookieless-tracking/). - **[Technical SEO](https://cookingmetrics.com/services/technical-seo/)**: Have you migrated your site, or are pages missing from Google? We review crawling, indexing, structure and performance. [How we approach technical SEO](https://cookingmetrics.com/services/technical-seo/). - **[SEO for AI search (GEO)](https://cookingmetrics.com/services/seo-ai-geo/)**: We review whether search engines and assistants can access your pages and understand their content. [What we can improve for AI search](https://cookingmetrics.com/services/seo-ai-geo/). ### Solutions - **[Google Analytics self-check](https://cookingmetrics.com/google-analytics-self-check/)** (Status: Available) - **[GA4 Report Generator](https://cookingmetrics.com/product/ga4-report-generator/)** (Status: Beta): A tool in beta that already generates Google Analytics reports. Ask about available features and the scope for your project. [Explore GA4 Report Generator](https://cookingmetrics.com/product/ga4-report-generator/). - **[IndexNow Connect](https://cookingmetrics.com/product/indexnow-connect/)** (Status: Available for Tiendanube): Notifies search engines participating in IndexNow of new, updated or deleted URLs. [How IndexNow Connect works](https://cookingmetrics.com/product/indexnow-connect/). - **[AI SEO Analysis](https://cookingmetrics.com/product/ai-seo-analysis/)** (Status: In development): *Coming soon.* An automated audit of how AI assistants and search engines access and use your content. [Learn about AI SEO Analysis](https://cookingmetrics.com/product/ai-seo-analysis/). **Let's talk about your measurement:** [Book a call](https://cookingmetrics.com/about-martin-garay/) · [CookingMetrics](https://cookingmetrics.com/)