An open brass pocket compass standing on a dark surface

MCP servers

How do I connect Google Analytics 4 to Claude or ChatGPT with the GA4 MCP server?

By The Tofu team ·

Google publishes an official, open-source Google Analytics MCP server that lets an AI assistant query your GA4 data. It runs on your own computer, so you can add it to Claude Desktop, Claude Code or Cursor with a short config entry. ChatGPT and Claude on the web can't start it, because they connect only to remote servers. You need Python, a Google Cloud project with the Analytics Admin and Data APIs turned on, and credentials for an account with at least Viewer access to the property. By default it only reads.

As of October 2026.

What is the Google Analytics MCP server?

It's a free server from Google that connects GA4 to AI assistants through the Model Context Protocol (MCP). The code sits in the googleanalytics organization on GitHub under the Apache 2.0 license, and the package on PyPI is analytics-mcp; version 0.8.0 came out on October 22, 2026. The GitHub README calls it experimental. It runs as a local process that your AI app starts, and it calls the Google Analytics Admin API and Data API for you.

Is the GA4 MCP server read-only?

By default, yes. Google's developer page says it "is available for read requests only" and "can't create, modify, or delete your Google Analytics configuration or settings." The GitHub README for version 0.8.0 describes one exception you have to switch on: start the server with --allow-write and add the analytics.edit scope, and it can create property annotations. The code lists that as its only write tool, and Google's developer page doesn't mention it yet.

What can I ask it about my GA4 data?

You can ask about anything its reporting tools return for the properties your account can see. The tools list your accounts and properties, show a property's details, its Google Ads links and annotations, list custom dimensions and metrics, and run standard, realtime, funnel and conversions reports. Google's sample prompts include "How many users did I have yesterday?", "What were my top selling products yesterday?" and "What custom dimensions and custom metrics are configured in my property?" If you also want Google Ads data in the same chat, add the Google Ads MCP server as well.

What do I need before I set it up?

You need four things, per Google's setup page:

  • Python 3.10 or later, plus pipx or uv to run the server.
  • A Google Cloud project with the Google Analytics Admin API (analyticsadmin.googleapis.com) and the Google Analytics Data API (analyticsdata.googleapis.com) enabled.
  • A Google account or service account with at least the Viewer role on the GA4 property, granted in the Google Analytics admin screens.
  • Application Default Credentials with the read-only Analytics scope. Google gives this command for a user account:
gcloud auth application-default login \
  --scopes="https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform"

When it finishes, copy the path it prints after "Credentials saved to file". Your AI app's config needs that path and your Cloud project ID. A service account works too: point the config at its JSON key file, or impersonate it by adding --impersonate-service-account=SERVICE_ACCOUNT_EMAIL to the same command.

How do I add it to Claude Desktop or Claude Code?

For Claude Desktop, add the server to claude_desktop_config.json. Google gives the path as ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows:

{
  "mcpServers": {
    "analytics-mcp": {
      "command": "pipx",
      "args": ["run", "analytics-mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
        "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"
      }
    }
  }
}

For Claude Code, Google's developer page gives this command (the README's version sets GOOGLE_PROJECT_ID instead):

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

The --scope user flag makes the server available in all your projects. Type /mcp inside Claude Code to check that it connected.

How do I add it to Cursor or Gemini CLI?

For Cursor, add the server to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json to use it everywhere. Google's example runs it with uvx:

{
  "mcpServers": {
    "google-analytics-mcp": {
      "command": "uvx",
      "args": ["--from", "analytics-mcp", "google-analytics-mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
        "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"
      }
    }
  }
}

For Gemini, Google's two pages disagree. The GitHub README still documents Gemini CLI or Gemini Code Assist, with the server added under mcpServers in ~/.gemini/settings.json; its example sets GOOGLE_PROJECT_ID rather than GOOGLE_CLOUD_PROJECT. Google's developer page, updated October 22, 2026, says "Gemini CLI is deprecated" and documents Antigravity CLI and Antigravity IDE instead, with the block in ~/.gemini/config/mcp_config.json (or .agents/mcp_config.json in your workspace). In Antigravity CLI, run agy and enter /mcp to confirm it's connected.

Can I use the GA4 MCP server with ChatGPT?

Not directly, and Google doesn't document a ChatGPT setup. ChatGPT adds a custom MCP server from a server URL (over SSE or streaming HTTP) or through OpenAI's Secure MCP Tunnel, while Google's server only runs locally over standard input and output. OpenAI says its tunnel can forward to a local command, but that is a developer setup: it needs a tunnel in an OpenAI Platform organization, tunnel permissions, and a ChatGPT workspace that allows custom MCP servers. Claude on the web has the same limit, since Anthropic says custom connectors must reach a server over the public internet.

If you want GA4 in ChatGPT without that work, hosted third-party connectors exist. Windsor.ai and Supermetrics, for example, both list GA4 among the sources their MCP connections cover. They aren't made by Google, and they need their own accounts.

Is there a hosted version from Google?

Not one Google documents. Google Cloud's list of remote MCP servers, updated October 26, 2026, includes BigQuery, Gmail, Google Drive and Google Calendar, with no Google Analytics entry. Windsor.ai, a reporting vendor, wrote in a guide updated October 1, 2026 that Google also runs a remote MCP endpoint for the Analytics Data API. It says it tested the endpoint on September 30, 2026, saw four reporting tools, and treats it as unannounced because its reference page returned an error. Google hasn't published docs for it, so don't plan around it.

What are the limits?

The main limits come from the server's experimental status and from the Data API's quotas:

  • It's labeled experimental, and Google's developer page and the README don't list quite the same tools.
  • Every report draws on your property's Data API quota. A standard property gets 200,000 core tokens a day and 40,000 an hour, and one Cloud project can use 14,000 tokens an hour per property. Analytics 360 properties get 10 times those amounts. Daily quotas reset at midnight Pacific time.
  • A standard property can run 10 core requests at the same time.
  • Requests with age, gender, interest or audience dimensions may be thresholded, which Google applies so a report can't reveal individual users' demographics or interests. A property gets 120 such requests an hour.
  • It runs as a local process, so it works only while your computer and AI app are running.
  • Apart from the optional annotation tool, it can't change settings, audiences or conversions.

What are the common errors and how do I fix them?

Most errors come from APIs that aren't enabled, a missing quota project or a wrong credentials path. The first five rows are Google's troubleshooting list; the last comes from the server's code:

ErrorFix
403 PERMISSION_DENIEDEnable both Analytics APIs in the project set in GOOGLE_CLOUD_PROJECT, and give the account at least the Viewer role on the property.
Request had insufficient authentication scopesRun gcloud auth application-default login again with the analytics.readonly and cloud-platform scopes.
403 ACCESS_NOT_CONFIGURED or a missing quota projectSet GOOGLE_CLOUD_PROJECT in the server's env, or run gcloud auth application-default set-quota-project YOUR_PROJECT_ID. Google's developer page uses GOOGLE_CLOUD_PROJECT throughout. The README's text also recommends GOOGLE_CLOUD_PROJECT, but its config examples set GOOGLE_PROJECT_ID.
401 UNAUTHENTICATED or credentials file not foundUse an absolute path for GOOGLE_APPLICATION_CREDENTIALS, not ~ or $HOME, and log in again if your credentials expired.
spawn pipx ENOENT, uvx: command not found or a Python version errorInstall Python 3.10 or later. Desktop apps often don't see your shell's PATH, so put the full path from which pipx or which uvx in command.
A write tool fails with a permission errorThe code's error hint says write tools need the analytics.edit scope and at least the Marketer or Editor role on the property.

Sources

Related answers

More on

Let an agent build your next campaign.

Tofu Ads Agent reads your CRM, plans the funnel, builds the audience and creative, and stages full campaigns across LinkedIn, Google and Meta for your approval.

Try it free Get a demo