Google Analytics 4 MCP server for AI agents

The Google Analytics MCP server allows you to query your Google Analytics 4 data using natural language through Claude, Cursor, and other MCP clients. It provides access to over 200 GA4 dimensions and metrics, enabling you to analyze website traffic, user behavior, and analytics data through conversational interfaces.

Prerequisites

Before installing the server, ensure you have:

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

You can verify your Python setup with these commands:

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

# Check pip
pip --version
pip3 --version

Setting Up 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 Reporting API" → Click "Enable"
- 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

Installing the MCP Server

Choose one of these installation methods:

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

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

Using the GA4 MCP Server

Once configured, you can ask your MCP client various types of questions:

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

2. User Behavior Analysis

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

3. Traffic Source Performance

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

4. Content Performance

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

Available Tools

The server provides 5 main tools:

get_ga4_data - Retrieve GA4 data with custom dimensions and metrics
list_dimension_categories - Browse available dimension categories
list_metric_categories - Browse available metric categories
get_dimensions_by_category - Get dimensions for a specific category
get_metrics_by_category - Get metrics for a specific category

Dimensions & Metrics

Access to over 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

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

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

See the official Claude Code MCP documentation for more details.

For Cursor

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.

Adding an MCP server to Cursor globally

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": {
        "ga4-analytics": {
            "command": "python3",
            "args": [
                "-m",
                "ga4_mcp_server"
            ],
            "env": {
                "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json",
                "GA4_PROPERTY_ID": "123456789"
            }
        }
    }
}

Adding an MCP server to a project

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.

How to use the MCP server

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.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect

Google Analytics 4 MCP server