GA4 MCP Server

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.10+
• 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
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

git clone https://github.com/luminarylane/ga4-mcp.git
cd ga4-mcp
pip install -r requirements.txt

Configuration

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "ga4": {
      "command": "python",
      "args": ["/path/to/ga4-mcp/ga4_server.py"],
      "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)

Alternatively, place service_account_credentials.json in the ga4-mcp/ directory.

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 for valid names. Common mistakes: sessions not session, sessionSource not source, pagePath not page.

Contributing

1. Fork the repo
2. Create a feature branch (git checkout -b feat/my-feature)
3. Make changes and test locally
4. Submit a pull request

License

MIT License — see LICENSE for details.

Acknowledgments

• Anthropic for the MCP specification
• Google Analytics Data API for the reporting API