io.github.surendranb/google-analytics-mcp

Official

by surendranb · Python

GA4 MCP server for AI agents: schema discovery, server-side aggregation, analysis-ready defaults.

This Model Context Protocol (MCP) server provides Google Analytics 4 (GA4) capabilities for AI agents, including real-time query exploration, schema discovery, server-side metric aggregation, and analysis-ready defaults. It also supports audience insights, using GA4 data in a form intended for downstream agent analysis.

🛠️ Key Features

Real-time query exploration
Schema discovery
Metric aggregation (server-side)
Analysis-ready defaults
Audience insights

🚀 Use Cases

Let AI agents explore GA4 queries in real time
Use discovered GA4 schemas to structure analytics requests
Aggregate GA4 metrics for analysis workflows
Generate audience insight outputs for agent-driven reporting

⚡ Developer Benefits

MCP integration for AI agents
Schema discovery to guide request construction
Aggregated metrics suitable for downstream analysis

⚠️ Limitations

Focus is specifically on Google Analytics 4 (GA4) functionality

Topics

ai-agentanalyticsclaude-mcpga4gemini-extensiongoogle-analyticsmcp-servermodel-context-protocolai-agentsclaudecursormcp

README.md4 KBView on GitHub

Google Analytics 4 (GA4) MCP Server 📊

Model Context Protocol (MCP) server for Google Analytics 4: real-time query exploration, schema discovery, metric aggregation, and audience insights for AI agents.

OpenSSF Scorecard

🌐 Live Documentation & Web Portal: https://ga4.builditwithai.xyz

⚡ Quickstart

bash

# 1-Line Universal Installer (Auto-configures Claude Desktop, Cursor, Claude Code, Antigravity, VS Code, Zed, Windsurf)
curl -fsSL "https://ga4.builditwithai.xyz/install" | bash

# Or run directly via your preferred runtime:
uvx google-analytics-mcp
uvx --from google-analytics-mcp ga4-mcp-server
python -m ga4_mcp
npx -y @surendranb/google-analytics-mcp

🤖 Client Setup

A. Claude Code (CLI)

bash

claude mcp add google-analytics -- uvx google-analytics-mcp

B. Cursor & Google Antigravity (`mcp.json`)

json

{
  "mcpServers": {
    "google-analytics": {
      "command": "uvx",
      "args": ["google-analytics-mcp"]
    }
  }
}

C. Claude Desktop (`claude_desktop_config.json`)

json

{
  "mcpServers": {
    "google-analytics": {
      "command": "uvx",
      "args": ["google-analytics-mcp"],
      "env": {
        "GA4_PROPERTY_ID": "your_ga4_property_id",
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service_account.json"
      }
    }
  }
}

D. VS Code (Cline / Roo Code / Continue)

json

{
  "mcpServers": {
    "google-analytics": {
      "command": "npx",
      "args": ["-y", "@surendranb/google-analytics-mcp"]
    }
  }
}

🛠️ Tools & Capabilities

Tool Name	Parameters	Description	Return Type
`get_ga4_data`	`dimensions` (list), `metrics` (list), `date_ranges` (list), `limit` (int)	Runs multi-dimensional GA4 reports with automated metric totals and server-side aggregation.	`JSON / Markdown`
`list_accounts`	(none)	Lists all accessible Google Analytics accounts and permission levels.	`JSON`
`list_properties`	`account_id` (optional)	Lists all GA4 properties associated with an account.	`JSON`
`get_property_metadata`	`property_id` (optional)	Fetches complete dimension and metric schemas, custom definitions, and compatibility rules.	`JSON`
`run_realtime_report`	`metrics` (list), `dimensions` (list)	Queries real-time active users and event counts from the last 30 minutes.	`JSON`
`search_skills`	`query` (string)	Searches built-in GA4 analytical playbooks (e-commerce, channel attribution, bot filtering).	`Markdown`
`skill_read`	`skill_name` (string)	Dynamically loads procedural skills and analytical guides from GitHub.	`Markdown`
`skills_list`	(none)	Lists all available live GA4 analytical skills.	`JSON`

🧠 Dynamic Skills & Guided Playbooks

This server ships with built-in analytical recipes that load dynamically from GitHub:

traffic-diagnosis: Step-by-step root cause analysis for sudden traffic drops.
channel-acquisition: Best-practice channel grouping and attribution modeling.
ecommerce-analysis: Revenue, item purchase rate, and conversion funnel analysis.
ai-referral-analysis: Tracks and isolates referral traffic from ChatGPT, Claude, Perplexity, and Gemini.

🔒 Telemetry & Privacy

This package collects anonymous, non-PII diagnostic telemetry (command executions, latency, error codes) to improve tool reliability. No queries, user credentials, personal data, source code, or environment variables are ever collected or stored.

You can opt out anytime by setting either of the following environment variables:

bash

export DO_NOT_TRACK=1
# or
export MCP_TELEMETRY_OPT_OUT=1

📄 License

MIT License. See LICENSE for details.

Install

Configuration

Environment variables

GOOGLE_APPLICATION_CREDENTIALSrequiredsecret

Absolute path to your Google Cloud service account JSON key with GA4 property access.

GA4_PROPERTY_IDrequired

Numeric GA4 Property ID to query, for example 123456789.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "google-analytics-mcp": {
      "command": "uvx",
      "args": [
        "google-analytics-mcp"
      ],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "<YOUR_GOOGLE_APPLICATION_CREDENTIALS>",
        "GA4_PROPERTY_ID": "<YOUR_GA4_PROPERTY_ID>"
      }
    }
  }
}

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

Google Analytics 4 (GA4) MCP Server 📊

⚡ Quickstart

🤖 Client Setup

A. Claude Code (CLI)

B. Cursor & Google Antigravity (mcp.json)

C. Claude Desktop (claude_desktop_config.json)

D. VS Code (Cline / Roo Code / Continue)

🛠️ Tools & Capabilities

🧠 Dynamic Skills & Guided Playbooks

🔒 Telemetry & Privacy

📄 License

Install

Configuration

Related servers

B. Cursor & Google Antigravity (`mcp.json`)

C. Claude Desktop (`claude_desktop_config.json`)