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).

⚡ Token Optimization - READ THIS FIRST!

IMPORTANT: Google Analytics reports can return large datasets that consume significant tokens. 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 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

Option 2: Use with npx (no installation needed)

🔧 Configuration

This server requires different credentials for reading data vs sending events:

For Reading Data (Google Analytics Data API)

You need a Service Account with access to your GA4 property:

1. Go to Google Cloud Console

2. Create or select a project

3. Enable the Google Analytics Data API

4. Create a Service Account:

   • Go to "IAM & Admin" > "Service Accounts"

   • Click "Create Service Account"

   • Give it a name (e.g., "GA4 MCP Reader")

   • Grant the "Viewer" role

   • Create a JSON key and download it

5. Add the service account email to your GA4 property:

   • Go to GA4 Admin > Property Access Management

   • Add the service account email with "Viewer" role

6. Get your Property ID:

   • Go to GA4 Admin > Property Settings

   • Copy the Property ID (numeric, e.g., "123456789")

For Sending Events (Measurement Protocol)

You need a Measurement ID and API Secret:

1. Go to GA4 Admin > Data Streams

2. Select your data stream (web, iOS, or Android)

3. Copy the Measurement ID (format: G-XXXXXXXXXX)

4. Click "Measurement Protocol API secrets"

5. Click "Create" to generate a new API secret

6. Copy the secret value

Environment Variables

Set these environment variables:

🔌 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

Or if installed globally:

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

Restart Cursor after updating the configuration.

🛠️ Available Tools

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:

ga_run_realtime_report

Get real-time data (last 30 minutes).

Example:

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:

ga_run_funnel_report

Run funnel analysis to track user progression.

Example:

ga_batch_run_reports

Run multiple reports in a single request.

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

Measurement Protocol (Sending Events)

ga_send_event

Send custom events to GA4.

Example:

ga_validate_event

Validate events before sending (uses debug endpoint).

ga_send_pageview

Send page view events.

Example:

ga_send_purchase

Send ecommerce purchase events.

Example:

ga_send_login

Send login events.

ga_send_signup

Send user registration events.

ga_send_add_to_cart

Send add-to-cart events.

ga_send_begin_checkout

Send checkout initiation events.

📖 Usage Examples

See EXAMPLES.md for practical usage examples in Spanish.

Example: Get users by country (last 7 days)

Claude will use ga_run_report:

Example: Track a purchase

Claude will use ga_send_purchase:

🔍 Debugging

Enable debug logging by setting:

For Measurement Protocol, use ga_validate_event to check events before sending them live.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• GitHub Repository

• npm Package

• MCP Documentation

• GA4 Data API Documentation

• Measurement Protocol Documentation

🆘 Support

For issues and questions:

• GitHub Issues

• MCP Community Discord

📝 Changelog

See CHANGELOG.md for version history.