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
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
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
- Open the Google Cloud Console.
- Enable the Google Analytics Data API.
- Under APIs & Services → Credentials, create a Service Account.
- 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
- Open Google Analytics.
- Select your GA4 Property → Open Admin (gear icon) → Property Access Management.
- Add the Service Account email (found inside the JSON key as
client_email) with the Viewer role.
3. Find Your GA4 Property ID
- In Google Analytics Admin → Property Details.
- 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
1 maintainer
Metadata
1 maintainer
Release files for google-analytics-mcp 2.9.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| google_analytics_mcp-2.9.0.tar.gz | 47.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| google_analytics_mcp-2.9.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 93.5 kB
Release files / google_analytics_mcp-2.9.0.tar.gz
| Download URL | google_analytics_mcp-2.9.0.tar.gz |
|---|---|
| Size | 47.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
331bfdc515767e2ac78806354b3643abb4288ce27585ce4add41dc269122475c
|
|
BLAKE2b-256 checksum How to use checksums |
f578a02ca6d4b5673c095bb21592645f032a6febb5e489be4ae4b7e73ef1874f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 1, 2026.
Transparency logRelease files / google_analytics_mcp-2.9.0-py3-none-any.whl
| Download URL | google_analytics_mcp-2.9.0-py3-none-any.whl |
|---|---|
| Size | 46.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1547ec64c83fc7ce466789195d44e37fef1c8336d7db0fa2e1b26fda474f2449
|
|
BLAKE2b-256 checksum How to use checksums |
d958ffef2c45e465c6cbf9a1d5deb1d7aed981963630d35bf269df5ad689e174
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 1, 2026.
Transparency log
