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

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:

Go to Google Cloud Console
Create or select a project
Enable the Google Analytics Data API
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
Add the service account email to your GA4 property:
- Go to GA4 Admin > Property Access Management
- Add the service account email with "Viewer" role
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:

Go to GA4 Admin > Data Streams
Select your data stream (web, iOS, or Android)
Copy the Measurement ID (format: G-XXXXXXXXXX)
Click "Measurement Protocol API secrets"
Click "Create" to generate a new API secret
Copy the secret value

Environment Variables

Set these environment variables:

# For Data API (reading)
export GA_SERVICE_ACCOUNT_JSON=/path/to/service-account.json
# Or provide JSON directly:
# export GA_SERVICE_ACCOUNT_JSON='{"type":"service_account","project_id":"..."}'

export GA_PROPERTY_ID=123456789

# For Measurement Protocol (writing)
export GA_MEASUREMENT_ID=G-XXXXXXXXXX
export GA_API_SECRET=your-api-secret-here

🔌 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",
        "GA_MEASUREMENT_ID": "G-XXXXXXXXXX",
        "GA_API_SECRET": "your-api-secret"
      }
    }
  }
}

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",
        "GA_MEASUREMENT_ID": "G-XXXXXXXXXX",
        "GA_API_SECRET": "your-api-secret"
      }
    }
  }
}

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",
        "GA_MEASUREMENT_ID": "G-XXXXXXXXXX",
        "GA_API_SECRET": "your-api-secret"
      }
    }
  }
}

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:

{
  "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.

Example:

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

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

{
  "events": [{
    "name": "button_click",
    "params": {
      "button_id": "cta_signup",
      "page": "/landing"
    }
  }],
  "user_id": "user123"
}

`ga_validate_event`

Validate events before sending (uses debug endpoint).

`ga_send_pageview`

Send page view events.

Example:

{
  "page_location": "https://example.com/products",
  "page_title": "Products",
  "user_id": "user123"
}

`ga_send_purchase`

Send ecommerce purchase events.

Example:

{
  "transaction_id": "T12345",
  "value": 99.99,
  "currency": "USD",
  "items": [{
    "item_id": "SKU123",
    "item_name": "Product Name",
    "price": 99.99,
    "quantity": 1
  }]
}

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

Show me active users by country for the last 7 days

Claude will use ga_run_report:

{
  "dateRanges": [{"startDate": "7daysAgo", "endDate": "today"}],
  "dimensions": [{"name": "country"}],
  "metrics": [{"name": "activeUsers"}],
  "limit": 10,
  "orderBys": [{"metric": {"metricName": "activeUsers"}, "desc": true}]
}

Example: Track a purchase

Send a purchase event for order #12345, $99.99 USD

Claude will use ga_send_purchase:

{
  "transaction_id": "12345",
  "value": 99.99,
  "currency": "USD",
  "items": [{
    "item_id": "product_1",
    "item_name": "Example Product",
    "price": 99.99,
    "quantity": 1
  }]
}

🔍 Debugging

Enable debug logging by setting:

export DEBUG=mcp-google-analytics:*

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

🆘 Support

For issues and questions:

📝 Changelog

See CHANGELOG.md for version history.

Made with ❤️ by GoMakers.ai

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.github/ISSUE_TEMPLATE		.github/ISSUE_TEMPLATE
src		src
.env.example		.env.example
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
DEPLOYMENT.md		DEPLOYMENT.md
EXAMPLES.md		EXAMPLES.md
LICENSE		LICENSE
PROJECT_SUMMARY.md		PROJECT_SUMMARY.md
QUICKSTART.md		QUICKSTART.md
README.md		README.md
TOKEN_OPTIMIZATION.md		TOKEN_OPTIMIZATION.md
package-lock.json		package-lock.json
package.json		package.json
run_test_event.js		run_test_event.js
run_test_event.mjs		run_test_event.mjs
tsconfig.json		tsconfig.json

License

leosepulveda/mcp-google-analytics

Folders and files

Latest commit

History

Repository files navigation

MCP Google Analytics Server

⚡ Token Optimization - READ THIS FIRST!

🚀 Quick Start

📦 Installation

Option 1: Install globally via npm

Option 2: Use with npx (no installation needed)

🔧 Configuration

For Reading Data (Google Analytics Data API)

For Sending Events (Measurement Protocol)

Environment Variables

🔌 Integration with Claude Desktop

🎯 Integration with Cursor

🛠️ Available Tools

Google Analytics Data API (Reading Data)

ga_run_report

ga_run_realtime_report

ga_get_metadata

ga_list_accounts

ga_list_properties

ga_get_property

ga_list_data_streams

ga_run_pivot_report

ga_run_funnel_report

ga_batch_run_reports

Measurement Protocol (Sending Events)

ga_send_event

ga_validate_event

ga_send_pageview

ga_send_purchase

ga_send_login

ga_send_signup

ga_send_add_to_cart

ga_send_begin_checkout

📖 Usage Examples

Example: Get users by country (last 7 days)

Example: Track a purchase

🔍 Debugging

🤝 Contributing

📄 License

🔗 Links

🆘 Support

📝 Changelog

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Languages

`ga_run_report`

`ga_run_realtime_report`

`ga_get_metadata`

`ga_list_accounts`

`ga_list_properties`

`ga_get_property`

`ga_list_data_streams`

`ga_run_pivot_report`

`ga_run_funnel_report`

`ga_batch_run_reports`

`ga_send_event`

`ga_validate_event`

`ga_send_pageview`

`ga_send_purchase`

`ga_send_login`

`ga_send_signup`

`ga_send_add_to_cart`

`ga_send_begin_checkout`

Packages