MCP Google Analytics

MCP Google Analytics Server

A Model Context Protocol (MCP) server for Google Analytics 4, providing comprehensive integration with both the Google Analytics Data API (for reading reports) and Measurement Protocol v2 (for sending events).

The GA4 MCP that reads AND writes. Most GA4 MCP servers (including Google's official one) are read-only. This one gives your AI agent the full loop: run reports and funnels, audit your setup (custom dimensions, key events, compatibility checks), send ecommerce and conversion events server-side, and verify them in the realtime report — 26 tools in one npx command.

Built for agencies too: every read tool accepts an optional propertyId, so one conversation can query all your clients' properties — no reconfiguration between clients. See Multi-Property Mode.

⚡ One-Click Install

You only need two values to start (same as any other GA4 MCP): the service account JSON and your property ID. Sending events is an optional extra.

Click Install in Cursor, then paste:

1. `GA_SERVICE_ACCOUNT_JSON` — path to the downloaded key file, or the JSON itself
2. `GA_PROPERTY_ID` — the numeric ID in GA4 Admin → Property Settings (e.g. 123456789)

That is enough to ask “users by country this week”. To also send events, add two more keys later (see Send events (optional)).

💡 Keep reports small

Reports can get large. This server is designed with token optimization in mind:

• All read tools default to 10 results - Adjust the limit parameter as needed
• Use specific date ranges - Avoid querying years of data at once
• Select only needed dimensions/metrics - Don't request everything
• Check [TOKEN_OPTIMIZATION.md](TOKEN_OPTIMIZATION.md) for detailed best practices

See the dedicated Token Optimization Guide for strategies to minimize token usage.

🚀 Quick Start

See QUICKSTART.md for a 5-minute setup guide, or follow the installation steps below.

📦 Installation

Option 1: Install globally via npm

npm install -g mcp-google-analytics

Option 2: Use with npx (no installation needed)

npx mcp-google-analytics

🔧 Configuration

Start with two values. That unlocks reports, funnels, realtime, and property audits — everything most people need, and the same setup every other GA4 MCP asks for.

1. Service account key

1. In Google Cloud Console, enable Google Analytics Data API.
2. IAM & Admin → Service Accounts → Create. Download a JSON key.
3. In GA4: Admin → Property Access Management → add the service account email as Viewer.

Use the file path or paste the JSON into GA_SERVICE_ACCOUNT_JSON.

2. Property ID

GA4 Admin → Property Settings → Property ID (numbers only, e.g. 123456789).

{

"mcpServers": { "google-analytics": { "command": "npx", "args": ["-y", "mcp-google-analytics"], "env": { "GA_SERVICE_ACCOUNT_JSON": "/path/to/service-account.json", "GA_PROPERTY_ID": "123456789" } } } }

You can now ask: *“Show me active users by country this week.”*

Send events (optional)

Only if you want the agent to record events (purchases, signups, custom events). Most GA4 MCPs cannot do this; it is extra, not required.

1. GA4 Admin → Data Streams → your stream → copy Measurement ID (G-XXXXXXXXXX).
2. Measurement Protocol API secrets → Create → copy the secret.

Add them next to the two values you already have:

"GA_MEASUREMENT_ID": "G-XXXXXXXXXX",

"GA_API_SECRET": "your-api-secret"

🏢 Multi-Property Mode (Agencies)

Every read tool accepts an optional propertyId argument that overrides the configured GA_PROPERTY_ID — so a single conversation can query any property the service account can access, with no reconfiguration between clients.

1. Grant your service account "Viewer" access on each client's GA4 property (or at account level).
2. Set only GA_SERVICE_ACCOUNT_JSON (GA_PROPERTY_ID becomes optional — if set, it acts as the default).
3. Discover properties, then query any of them:

Show me all my accounts and properties          → ga_get_account_summaries

Compare last week's active users between the → ga_run_report with propertyId "111111" Acme property and the Globex property and again with propertyId "222222"

propertyId accepts both 123456789 and properties/123456789. Event sending (Measurement Protocol) remains tied to the configured GA_MEASUREMENT_ID/GA_API_SECRET, since each data stream has its own secret.

🔌 Integration with Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{

"mcpServers": { "google-analytics": { "command": "npx", "args": ["-y", "mcp-google-analytics"], "env": { "GA_SERVICE_ACCOUNT_JSON": "/path/to/service-account.json", "GA_PROPERTY_ID": "123456789" } } } }

Or if installed globally:

{

"mcpServers": { "google-analytics": { "command": "mcp-google-analytics", "env": { "GA_SERVICE_ACCOUNT_JSON": "/path/to/service-account.json", "GA_PROPERTY_ID": "123456789" } } } }

Restart Claude Desktop after updating the configuration.

🎯 Integration with Cursor

Add to your Cursor MCP settings file:

macOS/Linux: ~/.cursor/mcp.json Windows: %USERPROFILE%\.cursor\mcp.json

{

"mcpServers": { "google-analytics": { "command": "npx", "args": ["-y", "mcp-google-analytics"], "env": { "GA_SERVICE_ACCOUNT_JSON": "/path/to/service-account.json", "GA_PROPERTY_ID": "123456789" } } } }

Restart Cursor after updating the configuration.

🛠️ Available Tools

At a Glance

Reading data (Google Analytics Data API) — all read tools default to 10 rows to save tokens:

Sending events (Measurement Protocol):

Google Analytics Data API (Reading Data)

ga_run_report

Run custom reports with dimensions and metrics.

Common Dimensions: date, city, country, deviceCategory, browser, pagePath, eventName, sessionSource, sessionMedium, sessionCampaignName

Common Metrics: activeUsers, sessions, screenPageViews, conversions, totalRevenue, engagementRate, averageSessionDuration

Example:

{

"dateRanges": [{"startDate": "7daysAgo", "endDate": "today"}], "dimensions": [{"name": "city"}], "metrics": [{"name": "activeUsers"}], "limit": 10 }

ga_run_realtime_report

Get real-time data (last 30 minutes).

Example:

{

"metrics": [{"name": "activeUsers"}], "dimensions": [{"name": "country"}], "limit": 10 }

ga_get_metadata

Get all available dimensions and metrics for your property.

Warning: Returns 500+ items. Use sparingly.

ga_list_accounts

List all GA accounts accessible to the service account.

ga_list_properties

List GA4 properties, optionally filtered by account ID.

ga_get_property

Get details about the configured property.

ga_list_data_streams

List data streams for the configured property.

ga_run_pivot_report

Run pivot table reports with row/column dimensions.

Example:

{

"dateRanges": [{"startDate": "7daysAgo", "endDate": "today"}], "dimensions": [{"name": "country"}, {"name": "deviceCategory"}], "metrics": [{"name": "activeUsers"}], "pivots": [{"fieldNames": ["deviceCategory"], "limit": 5}] }

ga_run_funnel_report

Run funnel analysis to track user progression.

Note: Funnel reporting uses the Data API v1alpha channel (the only channel where Google exposes it). Each step matches an event: set eventName per step, or omit it to use the step's name as the event name. For advanced matching, pass a full filterExpression.

Example:

{

"dateRanges": [{"startDate": "7daysAgo", "endDate": "today"}], "funnelSteps": [ {"name": "page_view"}, {"name": "add_to_cart"}, {"name": "begin_checkout"}, {"name": "Purchase", "eventName": "purchase"} ] }

ga_batch_run_reports

Run multiple reports in a single request.

Warning: Can return large datasets. Limit to 2-5 reports per batch.

ga_get_account_summaries

Get all accessible accounts with their properties in a single compact call. The fastest way to discover account and property IDs.

ga_list_custom_dimensions / ga_list_custom_metrics

List the custom dimensions and metrics defined for the property, including their API names (e.g., customEvent:plan_type) so yo