Google Analytics 4 MCP Server

mcp-name: io.github.surendranb/google-analytics-mcp

Connect Google Analytics 4 data directly to AI agents, analyst copilots, and MCP runtimes across Claude, ChatGPT, Gemini, Cursor, VS Code, and OpenClaw. Gives models analysis-ready GA4 access with live schema discovery, metric auto-aliasing, server-side aggregation, and autonomous self-healing defenses.

🌐 Website & Documentation: https://ga4mcp.com
🔗 Sister Project: Google Search Console MCP

⚡ Quickstart — 1-Line Installations

1. Universal 1-Line Installer (Recommended)

Auto-detects your system, configures Gemini CLI, Claude Desktop, Cursor, and VS Code automatically in 1 command:

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

2. Homebrew (macOS & Linux)

brew tap surendranb/tap
brew install google-analytics-mcp

3. NPX / Node.js (Claude Code, Cursor, VS Code, Windsurf)

Add to your MCP configuration file (claude_desktop_config.json or .cursor/mcp.json):

{
  "mcpServers": {
    "ga4-analytics": {
      "command": "npx",
      "args": ["-y", "google-analytics-mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/service-account-key.json",
        "GA4_PROPERTY_ID": "123456789"
      }
    }
  }
}

2. Gemini CLI Extension

Install directly into Google Gemini CLI with a single command:

gemini extensions install github.com/surendranb/google-analytics-mcp

3. Python uvx & Explicit python -m ga4_mcp

{
  "mcpServers": {
    "ga4-analytics": {
      "command": "uvx",
      "args": ["--from", "google-analytics-mcp", "ga4-mcp-server"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/service-account-key.json",
        "GA4_PROPERTY_ID": "123456789"
      }
    }
  }
}

Or run directly via ga4-mcp-server / python -m ga4_mcp:

{
  "mcpServers": {
    "ga4-analytics": {
      "command": "python",
      "args": ["-m", "ga4_mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/service-account-key.json",
        "GA4_PROPERTY_ID": "123456789"
      }
    }
  }
}

Related MCP server: GA4 MCP Server

🧠 Why AI Agents & Marketers Prefer This Server

• Autonomous Self-Healing: System directives automatically intercept schema hallucinations (like guessing legacy metric names or incorrect filter nesting) and guide models to self-correct via get_troubleshooting_guide.

• Metric Auto-Aliasing: Automatically maps legacy or common LLM requests like 'conversions' → 'keyEvents', preventing unnecessary query failures.

• Server-Side Aggregation: Computes property totals dynamically for non-time-series queries, so LLMs spend time answering business questions rather than parsing raw rows.

• Data Volume Protection: Runs quick row-count estimates before executing large queries (>2,500 rows) to prevent crashing model context windows.

• Multi-Platform Support: Native packages and manifests for PyPI, npm, Gemini CLI, Smithery, OpenClaw, and OpenAPI REST actions.

🔑 Setup & Credentials Guide

1. Create a Google Cloud Service Account

1. Open the Google Cloud Console.

2. Enable the Google Analytics Data API.

3. Under APIs & Services → Credentials, create a Service Account.

4. Create a JSON Key and save it locally on your machine (e.g. /Users/yourname/keys/ga4-key.json).

2. Grant Viewer Access in GA4

1. Open Google Analytics.

2. Select your GA4 Property → Open Admin (gear icon) → Property Access Management.

3. Add the Service Account email (found inside the JSON key as client_email) with the Viewer role.

3. Find Your GA4 Property ID

1. In Google Analytics Admin → Property Details.

2. Copy the numeric Property ID (e.g., 123456789).

🛠️ Available Tools

🔒 Telemetry & Privacy

GA4 MCP collects anonymous usage telemetry to help maintainers track release adoption, improve error defenses, and optimize latency. A one-time notice is printed on first run, before anything is sent.

What is collected (events: server_first_install, mcp_started, tool_executed, resource_read):

• A random installation UUID (stored in ~/.ga4_mcp/ — delete the folder to reset it) and a per-process session UUID. Never hardware-derived.

• Package version, OS, CPU architecture, Python version, install channel (uvx/pip/brew), shell and terminal names, timezone offset.

• Which MCP client is connecting (e.g. claude_code, cursor — from the MCP handshake or env-var presence; env values are never read).

• Tool name, latency, success/error status, error category, row counts, and query shape (number of dimensions/metrics, whether filters were used).

What is never collected: file paths and contents, environment variable values, credentials, IP addresses stored, GA4 property IDs, dimension/metric values, report data, prompts, usernames, or emails. Every outgoing string is additionally passed through a PII scrubber that redacts paths, emails, URLs, and keys as defense in depth.

Opt out with any of: DISABLE_TELEMETRY=1, GA_MCP_TELEMETRY=false, DO_NOT_TRACK=1, or NO_TELEMETRY=1.

📄 License & Author

Developed by Surendran B under the Apache License 2.0.
Website: https://ga4mcp.com