Google Analytics MCP Server

What is Google Analytics MCP Server?

Google Analytics MCP Server (google-analytics-mcp) is a community google analytics mcp server that connects Google Analytics 4 data to Claude, Cursor, VS Code and other MCP clients. You ask about traffic, channels and conversions in plain language, and it runs read-only GA4 Data API reports.

The project is maintained by surendranb and released under the MIT license. It is published on PyPI as google-analytics-mcp and on npm as @surendranb/google-analytics-mcp. It adds live schema discovery, server-side aggregation and built-in analytical "skills" on top of the GA4 Data API. It is not Google's own server. Google publishes a separate, experimental official Google Analytics MCP server.

How to use Google Analytics MCP Server?

Prerequisites: Python 3.10+ (or Node.js for the npm wrapper), a GA4 property with data, and Google Cloud credentials.

1. Create credentials. In Google Cloud Console, pick a project and enable the Google Analytics Data API. Create a service account and download its JSON key. Alternatively, use Application Default Credentials with gcloud auth application-default login.
2. Grant access in GA4. Copy the client_email from the JSON key. In Google Analytics, go to Admin → Property Access Management → Add users, paste the email and choose the Viewer role.
3. Note your property ID. Use the numeric GA4_PROPERTY_ID from Admin → Property details. This is not the G- measurement ID.
4. Set two environment variables: GA4_PROPERTY_ID and GOOGLE_APPLICATION_CREDENTIALS, the absolute path to the JSON key.

The README lists several ways to run the ga4 mcp server:

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

# Or run directly
uvx google-analytics-mcp
npx -y @surendranb/google-analytics-mcp

Claude Code

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

Make sure GA4_PROPERTY_ID and GOOGLE_APPLICATION_CREDENTIALS are set for the server process.

Claude Desktop

Add this to claude_desktop_config.json, then restart Claude Desktop:

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

Cursor

Use the same entry in ~/.cursor/mcp.json or a project .cursor/mcp.json. Reload Cursor and check that google-analytics shows as connected.

VS Code

In .vscode/mcp.json, VS Code uses a servers block:

{
  "servers": {
    "google-analytics": {
      "type": "stdio",
      "command": "uvx",
      "args": ["google-analytics-mcp"],
      "env": {
        "GA4_PROPERTY_ID": "123456789",
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/key.json"
      }
    }
  }
}

The project docs also include guides for Codex, Gemini, Copilot, Antigravity, Kiro, OpenCode and other clients. To check the setup, ask "List my GA4 properties."

Key features of Google Analytics MCP Server

• Multi-dimensional GA4 reports through the Google Analytics Data API, with GA4-computed totals and server-side aggregation
• Live schema discovery of standard and custom dimensions and metrics, so the model checks field names before it queries
• Real-time reports of active users and events from the last 30 minutes
• Built-in analytical playbooks ("skills") such as traffic-diagnosis, channel-acquisition, ecommerce-analysis and ai-referral-analysis
• Read-only access: it never changes your GA4 configuration
• Runs locally over stdio via uvx, pip, or the npm wrapper
• Anonymous telemetry that you can turn off with DO_NOT_TRACK=1 or MCP_TELEMETRY_OPT_OUT=1

Google Analytics MCP Server tools

• Reporting: get_ga4_data runs reports with dimensions, metrics, date ranges and a row limit. run_realtime_report queries the last 30 minutes.
• Discovery: list_accounts, list_properties and get_property_metadata show which accounts and properties the credentials can reach, and the full field schema of a property. The client guides also describe search_schema for finding the right field name.
• Skills: skills_list, search_skills and skill_read load guided analysis recipes, such as an ordered checklist for a traffic drop.

Use cases of Google Analytics MCP Server

• Diagnose a drop: "Why did organic traffic drop in the last 7 days?"
• Report on channels: "What were my top channels last week?"
• Find top content: "Which pages earned the most engaged sessions last week, excluding bots?"
• Track AI referrals: split traffic from ChatGPT, Claude, Perplexity and Gemini from search and direct.
• Check live traffic: "How many active users are on the site right now, by country?"
• Combine data sources: pair it with the author's Google Search Console MCP to compare search queries with on-site behavior.

Google Analytics MCP Server vs alternatives

• Official Google Analytics MCP server (googleanalytics/google-analytics-mcp, Google docs): built by Google, labeled experimental, Apache-2.0 licensed and read-only. It uses the Admin and Data APIs with Application Default Credentials. Choose it if you prefer Google's own implementation.
• This community google analytics mcp server: adds schema validation, aggregation helpers, real-time reports, playbooks and a multi-client installer, and is updated often.

Troubleshooting Google Analytics MCP Server

• Setup error about missing environment variables: set both GA4_PROPERTY_ID (numeric) and GOOGLE_APPLICATION_CREDENTIALS (absolute path to an existing JSON file) in the client's env block, then restart the client.
• "The service account does not have Viewer access to the GA4 property": the key works, but the service account is not on the property. Add its client_email as a Viewer under Property Access Management, using the property that matches GA4_PROPERTY_ID.
• 503 Reauthentication is needed: your gcloud Application Default Credentials expired. Run gcloud auth application-default login.
• 400 invalid dimension, metric or filter: the model guessed a Universal Analytics-era name. Use search_schema or get_property_metadata to find the GA4 name, then retry.
• Server unreachable in Cursor or VS Code: run uvx google-analytics-mcp in a terminal to confirm the runtime works, check the command spelling, and reload the window.