google-analytics-mcp
Advanced tools
Google Analytics 4 MCP Server with Smart Optimizations - Access GA4 data in Claude, Cursor and other MCP clients. Prevents context window crashes with intelligent data volume management.
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
---Check your Python setup:
# Check Python version (need 3.10+)
python --version
python3 --version
# Check pip
pip --version
pip3 --version
Required:
client_email fieldga4-mcp-server@your-project.iam.gserviceaccount.com)123456789)
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.
There are two supported ways to launch the server:
ga4-mcp-server when the installed console script is available on your PATHpython -m ga4_mcp when you want to use a specific interpreter or virtual environmentpython3 -m pip install google-analytics-mcp
If your machine uses python instead of python3, run:
python -m pip install google-analytics-mcp
Use this when ga4-mcp-server is available on your PATH:
{
"mcpServers": {
"ga4-analytics": {
"command": "ga4-mcp-server",
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json",
"GA4_PROPERTY_ID": "123456789"
}
}
}
}
Use this when you want to pin the exact Python runtime or when the console script is not on your PATH.
If python3 --version worked:
{
"mcpServers": {
"ga4-analytics": {
"command": "python3",
"args": ["-m", "ga4_mcp"],
"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"],
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json",
"GA4_PROPERTY_ID": "123456789"
}
}
}
}
git clone https://github.com/surendranb/google-analytics-mcp.git
cd google-analytics-mcp
python3 -m venv .venv
source .venv/bin/activate
python -m pip install .
If you plan to modify the package locally, use python -m pip install -e . instead.
MCP Configuration:
{
"mcpServers": {
"ga4-analytics": {
"command": "/full/path/to/google-analytics-mcp/.venv/bin/python",
"args": ["-m", "ga4_mcp"],
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json",
"GA4_PROPERTY_ID": "123456789"
}
}
}
}
Replace these placeholders in your MCP configuration:
/path/to/your/service-account-key.json with the absolute path to your JSON key123456789 with your numeric GA4 Property ID/full/path/to/google-analytics-mcp/.venv/bin/python with your virtual environment's Python path (Method B only)Once configured, ask your MCP client questions like:
Try these example queries to see the MCP's analytical capabilities:
Show me a map of visitors by city for the last 30 days, with a breakdown of new vs returning users
This demonstrates:
Compare average session duration and pages per session by device category and browser over the last 90 days
This demonstrates:
Show me conversion rates and revenue by traffic source and campaign, comparing last 30 days vs previous 30 days
This demonstrates:
What are my top 10 pages by engagement rate, and how has their performance changed over the last 3 months?
This demonstrates:
This MCP server includes built-in optimizations to prevent context window crashes and ensure smooth operation:
limit - Set maximum number of rows to returnproceed_with_large_dataset=True - Override warnings for large datasetsenable_aggregation=False - Disable automatic aggregationestimate_only=True - Get row count estimates without fetching data# 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
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).Access to 200+ GA4 dimensions and metrics organized by category:
If ga4-mcp-server is not found:
python -m ga4_mcpIf you get No module named ga4_mcp:
/full/path/to/python -m pip install google-analytics-mcp
Install the package with the exact interpreter you reference in your MCP configuration.
Permission errors:
# Try user install instead of system-wide
python -m pip install --user google-analytics-mcp
If the server says the credentials file is missing:
If the server says GA4_PROPERTY_ID is invalid or queries return no data:
123456789)G-XXXXXXXXXX)API quota/rate limit errors:
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
└── ...
Apache License 2.0
FAQs
Google Analytics 4 MCP Server with Smart Optimizations - Access GA4 data in Claude, Cursor and other MCP clients. Prevents context window crashes with intelligent data volume management.
We found that google-analytics-mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
GitHub account BufferZoneCorp published sleeper packages that later added credential theft, GitHub Actions tampering, fake go wrappers, and SSH persistence.
Research
/Security News
Socket found a malicious Intercom PHP package on Packagist using Composer plugin execution to steal credentials and spread across ecosystems.
Research
/Security News
Compromised intercom-client@7.0.4 npm package is tied to the ongoing Mini Shai-Hulud worm attack targeting developer and CI/CD secrets.