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](#-multi-property-mode-agencies).

[![npm version](https://badge.fury.io/js/mcp-google-analytics.svg)](https://www.npmjs.com/package/mcp-google-analytics)
[![npm downloads](https://img.shields.io/npm/dm/mcp-google-analytics.svg)](https://www.npmjs.com/package/mcp-google-analytics)
[![CI](https://github.com/leonardosepulvedat/mcp-google-analytics/actions/workflows/ci.yml/badge.svg)](https://github.com/leonardosepulvedat/mcp-google-analytics/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![smithery badge](https://smithery.ai/badge/lsepulvedatabares/mcp-google-analytics)](https://smithery.ai/servers/lsepulvedatabares/mcp-google-analytics)

## ⚡ 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.

[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=google-analytics&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1jcC1nb29nbGUtYW5hbHl0aWNzIl0sImVudiI6eyJHQV9TRVJWSUNFX0FDQ09VTlRfSlNPTiI6Ii9wYXRoL3RvL3NlcnZpY2UtYWNjb3VudC5qc29uIiwiR0FfUFJPUEVSVFlfSUQiOiIxMjM0NTY3ODkifX0=)

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)](#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](TOKEN_OPTIMIZATION.md) for strategies to minimize token usage.

## 🚀 Quick Start

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

## 📦 Installation

### Option 1: Install globally via npm

```bash
npm install -g mcp-google-analytics
```

### Option 2: Use with npx (no installation needed)

```bash
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](https://console.cloud.google.com/), 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`).

```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"
      }
    }
  }
}
```

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:

```json
"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`

```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:

```json
{
  "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`

```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:

| Tool | Purpose | Notes |
|---|---|---|
| `ga_run_report` | Custom reports with dimensions and metrics | Adjust `limit` as needed |
| `ga_run_realtime_report` | Real-time data (last 30 minutes) | Great for verifying sent events |
| `ga_get_metadata` | All available dimensions and metrics | Large response (500+ items), use sparingly |
| `ga_list_accounts` | List accessible GA accounts | |
| `ga_list_properties` | List GA4 properties | Aggregates all accounts if no `accountId` |
| `ga_get_property` | Details of the configured property | |
| `ga_list_data_streams` | Data streams of the property | Useful to find measurement IDs |
| `ga_run_pivot_report` | Pivot table reports | Responses can be very large |
| `ga_run_funnel_report` | Funnel analysis across event steps | Uses Data API v1alpha |
| `ga_batch_run_reports` | Multiple reports in one request | 2–5 reports per batch recommended |
| `ga_get_account_summaries` | All accounts and properties in one call | Fastest way to discover IDs |
| `ga_list_custom_dimensions` | Custom dimensions of the property | Discover API names for reports |
| `ga_list_custom_metrics` | Custom metrics of the property | Discover API names for reports |
| `ga_list_key_events` | Key events (conversions) of the property | Know what counts as a conversion |
| `ga_list_google_ads_links` | Google Ads accounts linked to the property | |
| `ga_check_compatibility` | Validate dimension/metric combos before reporting | Avoids wasted requests and error loops |

**Sending events (Measurement Protocol)**:

| Tool | Purpose |
|---|---|
| `ga_send_event` | Any custom GA4 event with parameters |
| `ga_validate_event` | Test an event against the debug endpoint without recording it |
| `ga_send_pageview` | Page/screen views |
| `ga_send_purchase` | Ecommerce purchases with transaction and items |
| `ga_send_login` | User logins |
| `ga_send_signup` | User registrations |
| `ga_send_view_item` | Product/item detail views |
| `ga_send_add_to_cart` | Add-to-cart events |
| `ga_send_begin_checkout` | Checkout initiations |
| `ga_send_refund` | Full or partial refunds |

### 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**:
```typescript
{
  "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**:
```types