Google Analytics MCP Logo

Google Analytics 4 MCP Server

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

PyPI version npm version PyPI Downloads GitHub stars License: Apache 2.0

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. 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 Jul 13, 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 Jul 13, 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

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.7.5.tar.gz (34.5 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.7.5-py3-none-any.whl (37.8 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: google_analytics_mcp-2.7.5.tar.gz
  • Upload date:
  • Size: 34.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for google_analytics_mcp-2.7.5.tar.gz
Algorithm Hash digest
SHA256 4a5db473ffc9a840746bd7e1e408a7409bcac36b01148754d84bc58bd8cc6652
MD5 657d3fe00dfe9f365fe2ee375a416937
BLAKE2b-256 8e7b0890a3b310b440333dd7d59aeaf52fe0477ff6521a073372e7bac3b2f1f4

See more details on using hashes here.

Provenance

The following attestation bundles were made for google_analytics_mcp-2.7.5.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.7.5-py3-none-any.whl.

File metadata

File hashes

Hashes for google_analytics_mcp-2.7.5-py3-none-any.whl
Algorithm Hash digest
SHA256 990191a1d6a272d4073d0295eabb4a84c7fbffb8d3aefacaafa9d3221cdee5da
MD5 896d2bac31cb1304b55de655cb416c94
BLAKE2b-256 dd9ba5c365262eda24e09008146bca5c5d00aeee9bb4f316f7e648683461b7f4

See more details on using hashes here.

Provenance

The following attestation bundles were made for google_analytics_mcp-2.7.5-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

2.11.1

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

This release

2.7.5 This release

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