google-analytics-mcp 2.5.0

Model Context Protocol for Google Analytics 4 (Data API) allowing autonomous agents to query dimensions and metrics. Gives agents analysis-ready GA4 access with schema discovery, server-side aggregation, and smart defaults.

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. 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"
      }
    }
  }
}

---

🧠 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

Tool Name	Purpose
get_ga4_data	Execute GA4 queries with dimensions, metrics, date ranges, and optional filters.
search_schema	Keyword search across 200+ GA4 dimension and metric API names.
get_property_schema	Inspect all available dimensions and metrics for your specific property.
list_metric_categories	Browse metric categories (User, Session, Revenue, Event).
list_dimension_categories	Browse dimension categories (Geography, Traffic Source, Device).
get_troubleshooting_guide	Self-healing guide for IAM permissions, setup, and filter syntax.

---

🔒 Telemetry & Privacy

GA4 MCP collects anonymous telemetry (mcp_started, tool_executed) to help maintainers track release adoption, improve error defenses, and optimize latency.

• No PII, no credentials, and no GA4 property data are ever collected.
• To opt out, set the environment variable: DISABLE_TELEMETRY=1.

---

📄 License & Author

Developed by Surendran B ([e-mail]) under the Apache License 2.0.
Website: https://ga4mcp.com