The Google Analytics MCP Server provides a seamless integration between Google Analytics 4 and Claude Desktop using the Model Context Protocol (MCP). It enables you to access, analyze, and visualize your Google Analytics data directly through Claude's interface with automatic OAuth authentication and token management.
Before setting up the MCP server, you'll need:
https://www.googleapis.com/auth/analyticshttps://www.googleapis.com/auth/analytics.readonlyclient_secret_[long-string].json in your project directory# Clone the repository
git clone https://github.com/yourusername/google-analytics-mcp-server.git
cd google-analytics-mcp-server
# Create virtual environment (recommended)
python3 -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
Create a .env file in your project directory:
# Copy the example file
cp .env.example .env
Edit .env with your credentials:
# Required: Path to OAuth credentials JSON file (downloaded from Google Cloud)
GOOGLE_ANALYTICS_OAUTH_CONFIG_PATH=/full/path/to/your/client_secret_file.json
Find your Claude Desktop configuration file:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
Windows:
%APPDATA%\Claude\claude_desktop_config.json
Edit the configuration file and add your Google Analytics MCP server:
{
"mcpServers": {
"google-analytics": {
"command": "/full/path/to/your/project/.venv/bin/python",
"args": [
"/full/path/to/your/project/server.py"
]
}
}
}
Important:
/ or double backslashes \\ in pathsClose and restart Claude Desktop to load the new configuration.
"List all my Google Analytics properties"
"List all my Google Analytics properties"
"Show me properties for account 123456789"
"What GA4 properties do I have access to?"
"Get page views for property 421301275 from 2025-01-01 to 2025-01-31"
"Show me top pages by page views for last month for property 421301275"
"Analyze page performance by country for property 421301275"
"Get active users for property 421301275 in the last 7 days"
"Show me user metrics by device category for property 421301275"
"Compare new vs returning users for last month"
"Analyze traffic sources for property 421301275 from 2025-01-01 to 2025-01-31"
"Show me which channels drive the most users to my site"
"Compare organic vs paid traffic performance"
"Get events data for property 421301275 in the last 30 days"
"Show me conversion events by source/medium"
"Which events are most popular on my site?"
"Create a report for property 421301275 with sessions, users, and page views by country from 2025-01-01 to 2025-01-31"
"Run a custom report showing bounce rate and engagement rate by device category"
"Generate a comprehensive traffic report with sessions, conversions, and revenue by source/medium"
run_report(
property_id="421301275",
start_date="2025-01-01",
end_date="2025-01-31",
metrics=["sessions", "totalUsers", "screenPageViews"],
dimensions=["country"],
limit=20
)
run_report(
property_id="421301275",
start_date="2025-01-01",
end_date="2025-01-31",
metrics=["sessions", "bounceRate", "engagementRate"],
dimensions=["deviceCategory", "operatingSystem"],
limit=50
)
run_report(
property_id="421301275",
start_date="2025-01-01",
end_date="2025-01-31",
metrics=["sessions", "conversions", "totalRevenue"],
dimensions=["source", "medium", "campaignName"],
limit=100
)
| Issue | Symptoms | Solution |
|---|---|---|
| No tokens found | "Starting OAuth flow" message | ✅ Normal for first-time setup - complete browser authentication |
| Token refresh failed | "Refreshing token failed" error | ✅ Delete google_analytics_token.json and re-authenticate |
| OAuth flow failed | Browser error or no response | Check credentials file path and internet connection |
| Permission denied | "Access denied" in browser | Ensure Google account has Analytics access |
| Issue | Symptoms | Solution |
|---|---|---|
| Environment variables missing | "Environment variable not set" | Check .env file and Claude config env section |
| File not found | "FileNotFoundError" | Verify absolute paths in configuration |
| Module import errors | "ModuleNotFoundError" | Run pip install -r requirements.txt |
| Python path issues | "Command not found" | Use absolute path to Python executable |
| Issue | Symptoms | Solution |
|---|---|---|
| Invalid property ID | "Property not found" | Use numeric format: 421301275 |
| API quota exceeded | "Quota exceeded" error | Wait for quota reset or request increase |
| Invalid date format | "Invalid date" | Use YYYY-MM-DD format: 2025-01-31 |
| No data returned | Empty results | Check date range and property access |
To add this MCP server to Claude Code, run this command in your terminal:
claude mcp add-json "google-analytics" '{"command":"/full/path/to/your/project/.venv/bin/python","args":["/full/path/to/your/project/server.py"]}'See the official Claude Code MCP documentation for more details.
There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.
If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.
To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".
When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:
{
"mcpServers": {
"google-analytics": {
"command": "/full/path/to/your/project/.venv/bin/python",
"args": [
"/full/path/to/your/project/server.py"
]
}
}
}To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.
Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.
The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.
You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.
To add this MCP server to Claude Desktop:
1. Find your configuration file:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json~/.config/Claude/claude_desktop_config.json2. Add this to your configuration file:
{
"mcpServers": {
"google-analytics": {
"command": "/full/path/to/your/project/.venv/bin/python",
"args": [
"/full/path/to/your/project/server.py"
]
}
}
}3. Restart Claude Desktop for the changes to take effect