# GA4 MCP Server

[![MCP](https://img.shields.io/badge/MCP-1.0-blue)](https://modelcontextprotocol.io)
[![Python](https://img.shields.io/badge/Python-3.11%2B-green)](https://python.org)
[![License](https://img.shields.io/badge/License-MIT-yellow)](LICENSE)

A Model Context Protocol (MCP) server that connects Claude Desktop (and other MCP clients) to the Google Analytics 4 Data API — run reports, view top pages, analyze traffic sources, check realtime users, and compare periods.

## Features

### 7 Analytics Tools

| Tool | Description |
|------|-------------|
| `ga4_list_properties` | List all GA4 properties accessible by the service account |
| `ga4_get_report` | Run a custom report with any dimensions and metrics |
| `ga4_get_top_pages` | Top pages by sessions with bounce rate and duration |
| `ga4_get_traffic_sources` | Traffic breakdown by source/medium |
| `ga4_get_conversions` | Conversion events and their counts |
| `ga4_get_realtime` | Realtime active users and top pages |
| `ga4_compare_periods` | Compare current vs previous period with percentage changes |

### Built-in Reliability

- **Token-bucket rate limiter** — respects GA4's 10 concurrent request limit
- **Auto-retry on 429/5xx** — exponential backoff (2s, 4s, 8s) up to 3 retries
- **Lazy imports** — defers heavy Google client libraries for fast MCP handshake
- **Actionable error messages** — guides users to fix permission, auth, and input errors

## Quick Start

### Prerequisites

- Python 3.11+
- A Google Cloud service account with GA4 access
- Claude Desktop (or any MCP-compatible client)

### Set Up Google Analytics Access

1. Create a [Google Cloud service account](https://console.cloud.google.com/iam-admin/serviceaccounts)
2. Enable the **Google Analytics Data API** and **Google Analytics Admin API** in your project
3. Download the service account JSON key file
4. In GA4: go to **Admin > Property Access Management** and add the service account email as a **Viewer**

### Installation

Run the published package without a global install:

```bash
uvx --from luminarylane-ga4-mcp luminarylane-ga4-mcp
```

The package is published on [PyPI](https://pypi.org/project/luminarylane-ga4-mcp/). Alternatively, install it with `pip install luminarylane-ga4-mcp`.

### Configuration

**Claude Desktop (`claude_desktop_config.json`):**
```json
{
  "mcpServers": {
    "ga4": {
      "command": "uvx",
      "args": ["--from", "luminarylane-ga4-mcp", "luminarylane-ga4-mcp"],
      "env": {
        "GA4_CREDENTIALS_PATH": "/path/to/service_account_credentials.json",
        "GA4_PROPERTY_ID": "123456789"
      }
    }
  }
}
```

**Environment variables:**

| Variable | Required | Description |
|----------|----------|-------------|
| `GA4_CREDENTIALS_PATH` | Yes | Path to service account JSON key file |
| `GA4_PROPERTY_ID` | No | Default property ID (can also pass per-tool) |

For local development only, credential files may be stored in paths excluded by `.gitignore`; never commit them. Prefer the explicit environment-variable path above.

## Usage Examples

Once configured, ask Claude to:

- "What are my top pages this month?"
- "Show me traffic sources for the last 7 days"
- "How does this week compare to last week?"
- "Are there any active users on the site right now?"
- "Run a report on sessions by country for the last 90 days"
- "What conversion events fired this week?"
- "List all GA4 properties I have access to"

## Rate Limits

GA4 Data API allows 10 concurrent requests per property. The server handles this with a client-side token bucket and exponential backoff retries.

## Troubleshooting

### Permission denied (403)

The service account doesn't have access to the GA4 property. Go to **GA4 Admin > Property Access Management** and add the service account email as a Viewer.

### Property not found (404)

Property IDs are numeric (e.g., `123456789`), not the measurement ID (`G-XXXXXXX`). Use `ga4_list_properties` to find valid IDs.

### Authentication failed (401)

Check that `GA4_CREDENTIALS_PATH` points to a valid service account JSON key file.

### Invalid dimension/metric (400)

Check the [GA4 Dimensions & Metrics Explorer](https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema) for valid names. Common mistakes: `sessions` not `session`, `sessionSource` not `source`, `pagePath` not `page`.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Never commit service-account credentials or OAuth tokens.

## Security

Report vulnerabilities privately using [GitHub's private vulnerability reporting](SECURITY.md); do not include credentials in public issues.

## License

MIT License — see [LICENSE](LICENSE) for details.

## Acknowledgments

- [Anthropic](https://anthropic.com) for the MCP specification
- [Google Analytics Data API](https://developers.google.com/analytics/devguides/reporting/data/v1) for the reporting API