Google Analytics MCP Logo

Google Analytics 4 MCP Server

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

PyPI Version CI Status GitHub Stars License

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

PyPI Downloads Breakdown and Trend
Powered by pypi.builditwithai.xyz

⚡ 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. One-Click for Cursor

Add to Cursor

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

5. Gemini CLI Extension

Install directly into Google Gemini CLI with a single command:

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

6. 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 usage telemetry to improve the server — no personal data, no GA4 report data, ever. Opt out anytime with DISABLE_TELEMETRY=1 or DO_NOT_TRACK=1.

📄 License & Author

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

Project links

Data verified by PyPI on Aug 15, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (2.11.3)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for surendranb from gravatar.com surendranb

Credits

Author: Surendran B

GitHub Statistics

Data verified by PyPI on Aug 15, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.10

Provides Extra

sdlc

Tags

google-analytics mcp mcp-server ai-agent analytics ga4 agentic-workflows llm

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

google_analytics_mcp-2.11.1.tar.gz (53.1 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

google_analytics_mcp-2.11.1-py3-none-any.whl (52.8 kB view details)

Uploaded Python 3

File details

Details for the file google_analytics_mcp-2.11.1.tar.gz.

File metadata

  • Download URL: google_analytics_mcp-2.11.1.tar.gz
  • Upload date:
  • Size: 53.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for google_analytics_mcp-2.11.1.tar.gz
Algorithm Hash digest
SHA256 8a1b89fde952c1ffa7a3f1fed44190e65d9e6502a7ceb2cd35a54bb45b0ad722
MD5 46e4badf121cc19f37adbdf1c0538d2c
BLAKE2b-256 bbd630e399ee1943eae6653b6ce0621be33e848a2c85c9f7900e7c056a61c0ec

See more details on using hashes here.

Provenance

The following attestation bundles were made for google_analytics_mcp-2.11.1.tar.gz:

Publisher: release.yml on surendranb/google-analytics-mcp

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file google_analytics_mcp-2.11.1-py3-none-any.whl.

File metadata

File hashes

Hashes for google_analytics_mcp-2.11.1-py3-none-any.whl
Algorithm Hash digest
SHA256 bd78c9a32be40caea61e26072316c8bc01ac286086cd597203a922c085ddd521
MD5 1a4839be9a7a729bc0277fc7171a39fc
BLAKE2b-256 4e36cde5472ff3f4c26f68f0327b0ae06d3bcdfd0e2dffbed56da06736e81c0c

See more details on using hashes here.

Provenance

The following attestation bundles were made for google_analytics_mcp-2.11.1-py3-none-any.whl:

Publisher: release.yml on surendranb/google-analytics-mcp

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

2.11.3

2 files

2.11.2

2 files

This release

2.11.1 This release

2 files

2.11.0

2 files

2.10.0

2 files

2.9.0

2 files

2.8.4

2 files

2.8.3

2 files

2.8.2

2 files

2.8.1

2 files

2.8.0

2 files

2.7.7

2 files

2.7.6

2 files

2.7.5

2 files

2.7.4

2 files

2.7.3

2 files

2.7.2

2 files

2.7.1

2 files

2.7.0

2 files

2.6.5

2 files

2.6.4

2 files

2.6.3

2 files

2.6.2

2 files

2.6.1

2 files

2.6.0

2 files

2.5.5

2 files

2.5.4

2 files

2.5.3

2 files

2.5.2

2 files

2.5.1

2 files

2.5.0

2 files

2.4.1

2 files

2.4.0

2 files

2.3.0

2 files

2.2.1

2 files

2.2.0

2 files

2.1.9

2 files

2.1.8

2 files

2.1.7

2 files

2.1.6

2 files

2.1.5

2 files

2.1.3

2 files

2.1.2

2 files

2.1.1

2 files

2.1.0

2 files

2.0.1

2 files

2.0.0

2 files

1.2.2

2 files

1.2.1

2 files

1.2.0

2 files

1.0.10

2 files

1.0.9

2 files

1.0.7

2 files

1.0.6

2 files

1.0.5

2 files

1.0.4

2 files

1.0.3

2 files

1.0.2

2 files

1.0.1

2 files

1.0.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page