Google Analytics MCP Server

mcp-name: io.github.surendranb/google-analytics-mcp

Connect Google Analytics 4 data to Claude, Cursor and other MCP clients. Query your website traffic, user behavior, and analytics data in natural language with access to 200+ GA4 dimensions and metrics.

Compatible with: Claude, Cursor and other MCP clients.

I also built a Google Search Console MCP that enables you to mix & match the data from both the sources

---

Prerequisites

Check your Python setup:

# Check Python version (need 3.10+)
python --version
python3 --version

# Check pip
pip --version
pip3 --version

Required:

Python 3.10 or higher
Google Analytics 4 property with data
Service account with Analytics Reporting API access

Step 1: Setup Google Analytics Credentials

Create Service Account in Google Cloud Console

Go to Google Cloud Console
Create or select a project:
- New project: Click "New Project" → Enter project name → Create
- Existing project: Select from dropdown
Enable the Analytics APIs:
- Go to "APIs & Services" → "Library"
- Search for "Google Analytics Data API" → Click "Enable"
Create Service Account:
- Go to "APIs & Services" → "Credentials"
- Click "Create Credentials" → "Service Account"
- Enter name (e.g., "ga4-mcp-server")
- Click "Create and Continue"
- Skip role assignment → Click "Done"
Download JSON Key:
- Click your service account
- Go to "Keys" tab → "Add Key" → "Create New Key"
- Select "JSON" → Click "Create"
- Save the JSON file - you'll need its path

Add Service Account to GA4

Get service account email:
- Open the JSON file
- Find the client_email field
- Copy the email (format: [email protected])
Add to GA4 property:
- Go to Google Analytics
- Select your GA4 property
- Click "Admin" (gear icon at bottom left)
- Under "Property" → Click "Property access management"
- Click "+" → "Add users"
- Paste the service account email
- Select "Viewer" role
- Uncheck "Notify new users by email"
- Click "Add"

Find Your GA4 Property ID

In Google Analytics, select your property
Click "Admin" (gear icon)
Under "Property" → Click "Property details"
Copy the Property ID (numeric, e.g., 123456789)
- Note: This is different from the "Measurement ID" (starts with G-)

Test Your Setup (Optional)

Verify your credentials:

pip install google-analytics-data

Create a test script (test_ga4.py):

import os
from google.analytics.data_v1beta import BetaAnalyticsDataClient

# Set credentials path
os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = "/path/to/your/service-account-key.json"

# Test connection
client = BetaAnalyticsDataClient()
print("✅ GA4 credentials working!")

Run the test:

python test_ga4.py

If you see "✅ GA4 credentials working!" you're ready to proceed.

Step 2: Install the MCP Server

Choose one method:

Method A: pip install (Recommended)

pip install google-analytics-mcp

MCP Configuration:

First, check your Python command:

python3 --version
python --version

Then use the appropriate configuration:

If python3 --version worked:

{
  "mcpServers": {
    "ga4-analytics": {
      "command": "python3",
      "args": ["-m", "ga4_mcp_server"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json",
        "GA4_PROPERTY_ID": "123456789"
      }
    }
  }
}

If python --version worked:

{
  "mcpServers": {
    "ga4-analytics": {
      "command": "python",
      "args": ["-m", "ga4_mcp_server"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json",
        "GA4_PROPERTY_ID": "123456789"
      }
    }
  }
}

Method B: GitHub download

git clone https://github.com/surendranb/google-analytics-mcp.git
cd google-analytics-mcp
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

MCP Configuration:

{
  "mcpServers": {
    "ga4-analytics": {
      "command": "/full/path/to/ga4-mcp-server/venv/bin/python",
      "args": ["/full/path/to/ga4-mcp-server/ga4_mcp_server.py"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json",
        "GA4_PROPERTY_ID": "123456789"
      }
    }
  }
}

Step 3: Update Configuration

Replace these placeholders in your MCP configuration:

/path/to/your/service-account-key.json with your JSON file path
123456789 with your GA4 Property ID
/full/path/to/ga4-mcp-server/ with your download path (Method B only)

Usage

Once configured, ask your MCP client questions like:

Discovery & Exploration

What GA4 dimension categories are available?
Show me all ecommerce metrics
What dimensions can I use for geographic analysis?

Traffic Analysis

What's my website traffic for the past week?
Show me user metrics by city for last month
Compare bounce rates between different date ranges

Multi-Dimensional Analysis

Show me revenue by country and device category for last 30 days
Analyze sessions and conversions by campaign and source/medium
Compare user engagement across different page paths and traffic sources

E-commerce Analysis

What are my top-performing products by revenue?
Show me conversion rates by traffic source and device type
Analyze purchase behavior by user demographics

Quick Start Examples

Try these example queries to see the MCP's analytical capabilities:

1. Geographic Distribution

Show me a map of visitors by city for the last 30 days, with a breakdown of new vs returning users

This demonstrates:

Geographic analysis
User segmentation
Time-based filtering
Data visualization

2. User Behavior Analysis

Compare average session duration and pages per session by device category and browser over the last 90 days

This demonstrates:

Multi-dimensional analysis
Time series comparison
User engagement metrics
Technology segmentation

3. Traffic Source Performance

Show me conversion rates and revenue by traffic source and campaign, comparing last 30 days vs previous 30 days

This demonstrates:

Marketing performance analysis
Period-over-period comparison
Conversion tracking
Revenue attribution

4. Content Performance

What are my top 10 pages by engagement rate, and how has their performance changed over the last 3 months?

This demonstrates:

Content analysis
Trend analysis
Engagement metrics
Ranking and sorting

🚀 Performance Optimizations

This MCP server includes built-in optimizations to prevent context window crashes and ensure smooth operation:

Smart Data Volume Management

Automatic row estimation - Checks data volume before fetching
Interactive warnings - Alerts when queries would return >2,500 rows
Optimization suggestions - Provides specific recommendations to reduce data volume

Server-Side Processing

Intelligent aggregation - Automatically aggregates data when beneficial (e.g., totals across time periods)
Smart sorting - Returns most relevant data first (recent dates, highest values)
Efficient filtering - Leverages GA4's server-side filtering capabilities

User Control Parameters

limit - Set maximum number of rows to return
proceed_with_large_dataset=True - Override warnings for large datasets
enable_aggregation=False - Disable automatic aggregation
estimate_only=True - Get row count estimates without fetching data

Example: Handling Large Datasets

# This query would normally return 2,605 rows and crash context window
get_ga4_data(
    dimensions=["date", "pagePath", "country"],
    date_range_start="90daysAgo"
)
# Returns: {"warning": True, "estimated_rows": 2605, "suggestions": [...]}

# Use monthly aggregation instead
get_ga4_data(
    dimensions=["month", "pagePath", "country"], 
    date_range_start="90daysAgo"
)
# Returns: Clean monthly data with manageable row count

Available Tools

The server provides a suite of tools for data reporting and schema discovery.

search_schema - Searches for a keyword across all available dimensions and metrics. This is the most efficient way to discover fields for a query.
get_ga4_data - Retrieve GA4 data with built-in intelligence for better and safer results (includes data volume protection, smart aggregation, and intelligent sorting).
list_dimension_categories - Lists all available dimension categories.
list_metric_categories - Lists all available metric categories.
get_dimensions_by_category - Gets all dimensions for a specific category.
get_metrics_by_category - Gets all metrics for a specific category.
get_property_schema - Returns the complete schema for the property (Warning: this can be a very large object).

Dimensions & Metrics

Access to 200+ GA4 dimensions and metrics organized by category:

Metric Categories

User Metrics: totalUsers, newUsers, activeUsers
Session Metrics: sessions, bounceRate, engagementRate
E-commerce: totalRevenue, transactions, conversions
Events: eventCount, conversions, event values
Advertising: adRevenue, returnOnAdSpend
And more specialized metrics

Troubleshooting

If you get "No module named ga4_mcp_server" (Method A):

pip3 install --user google-analytics-mcp

If you get "executable file not found":

Try the other Python command (python vs python3)
Use pip3 instead of pip if needed

Permission errors:

# Try user install instead of system-wide
pip install --user google-analytics-mcp

Credentials not working:

Verify the JSON file path is correct and accessible
Check service account permissions:
- Go to Google Cloud Console → IAM & Admin → IAM
- Find your service account → Check permissions
Verify GA4 access:
- GA4 → Admin → Property access management
- Check for your service account email
Verify ID type:
- Property ID: numeric (e.g., 123456789) ✅
- Measurement ID: starts with G- (e.g., G-XXXXXXXXXX) ❌

API quota/rate limit errors:

GA4 has daily quotas and rate limits
Try reducing the date range in your queries
Wait a few minutes between large requests

Project Structure

google-analytics-mcp/
├── ga4_mcp/                # Main package directory
│   ├── server.py           # Core server logic
│   ├── coordinator.py      # MCP instance
│   └── tools/              # Tool definitions (reporting, metadata)
├── pyproject.toml          # Package configuration for PyPI
├── requirements.txt        # Dependencies for local dev
├── README.md               # This file
└── ...

License

MIT License

谷歌分析

Google Analytics MCP Server

Prerequisites

Step 1: Setup Google Analytics Credentials

Create Service Account in Google Cloud Console

Add Service Account to GA4

Find Your GA4 Property ID

Test Your Setup (Optional)

Step 2: Install the MCP Server

Method A: pip install (Recommended)

Method B: GitHub download

Step 3: Update Configuration

Usage

Discovery & Exploration

Traffic Analysis

Multi-Dimensional Analysis

E-commerce Analysis

Quick Start Examples

1. Geographic Distribution

2. User Behavior Analysis

3. Traffic Source Performance

4. Content Performance

🚀 Performance Optimizations

Smart Data Volume Management

Server-Side Processing

User Control Parameters

Example: Handling Large Datasets

Available Tools

Dimensions & Metrics

Dimension Categories

Metric Categories

Troubleshooting

Project Structure

License

Cortex App 重磅来袭，抢先一步体验