Google Analytics MCP Server

A FastMCP server that provides AI agents with comprehensive access to Google Analytics 4 data via the Model Context Protocol (MCP).

Features

• 18 MCP tools covering all aspects of Google Analytics 4
• HTTP streaming transport for scalable deployments
• Service account authentication for automated server-to-server access
• Dynamic property discovery across all accessible GA4 accounts
• Historical reports with flexible dimensions, metrics, and date ranges
• Realtime data for current user activity
• Custom dimensions/metrics support

Installation

# Clone the repository
git clone <repo-url>
cd google-analytics-mcp

# Install dependencies with uv
uv sync

Configuration

Environment Variables

Variable	Required	Default	Description
GOOGLE_APPLICATION_CREDENTIALS	Yes*	-	Path to service account JSON file
MCP_HOST	No	0.0.0.0	Host to bind the server
MCP_PORT	No	8000	Port for the server

*Can also use Application Default Credentials (ADC) via gcloud auth application-default login

Google Cloud Setup

Step 1: Create a Google Cloud Project (if you don't have one)

1. Go to the Google Cloud Console
2. Click the project dropdown at the top of the page
3. Click New Project
4. Enter a project name (e.g., "GA MCP Server")
5. Click Create
6. Wait for the project to be created, then select it from the project dropdown

Step 2: Enable Required APIs

1. In the Google Cloud Console, go to APIs & Services > Library

2. Search for and enable these APIs:

   • Google Analytics Data API - for running reports
   • Google Analytics Admin API - for listing properties

   For each API:

   • Click on the API name
   • Click Enable

Step 3: Create a Service Account

1. In the Google Cloud Console, go to IAM & Admin > Service Accounts
2. Click + Create Service Account at the top
3. Fill in the details:
   • Service account name: ga-mcp-server
   • Service account ID: (auto-filled based on name)
   • Description: "Service account for Google Analytics MCP Server"
4. Click Create and Continue
5. Skip the optional "Grant this service account access" step (click Continue)
6. Skip the optional "Grant users access" step (click Done)

Step 4: Create and Download the Credentials JSON Key

1. In the Service Accounts list, find your newly created service account
2. Click on the service account email to open its details
3. Go to the Keys tab
4. Click Add Key > Create new key
5. Select JSON as the key type
6. Click Create
7. The JSON key file will automatically download to your computer
8. Important: Move this file to a secure location and note the path

   # Example: move to your project directory
   mv ~/Downloads/your-project-xxxxx.json ./credentials.json
   

Security Warning: This JSON file contains sensitive credentials. Never commit it to version control or share it publicly.

Step 5: Grant the Service Account Access to Google Analytics

The service account needs explicit access to your GA4 properties. Without this step, list_properties will return an empty list.

Find your service account email:

1. Go to Google Cloud Console > IAM & Admin > Service Accounts
2. Find your service account and copy the email address
   • It looks like: ga-mcp-server@your-project.iam.gserviceaccount.com

Grant access in Google Analytics:

1. Go to Google Analytics

2. Click the Admin gear icon (bottom left corner)

3. Choose where to grant access:

   Option A: Account Level (recommended) - Grants access to ALL properties under the account:

   • In the Account column, click Account Access Management

   Option B: Property Level - Grants access to a specific property only:

   • First select the property from the Property dropdown
   • In the Property column, click Property Access Management

4. Click the + button in the top right

5. Select Add users

6. In the "Email addresses" field, paste your service account email

7. Under "Direct roles and data restrictions":

   • Select Viewer (sufficient for reading all analytics data)
   • Leave data restrictions unchecked for full access

8. Click Add

Verify access was granted:

• The service account email should now appear in the users list
• You can test by calling list_properties - it should return your properties

Note: It may take a few minutes for permissions to propagate. If list_properties still returns empty, wait 2-3 minutes and try again.

Step 6: Set the Environment Variable

# Option 1: Set for current terminal session
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json

# Option 2: Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
echo 'export GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json' >> ~/.bashrc
source ~/.bashrc

# Option 3: Create a .env file in the project directory
cp .env.example .env
# Then edit .env and set the path to your credentials file

Alternative: Using Application Default Credentials (ADC)

If you prefer not to use a service account, you can authenticate with your personal Google account:

gcloud auth application-default login \
  --scopes=https://www.googleapis.com/auth/analytics.readonly

This is useful for local development but not recommended for production deployments.

Usage

Running the Server

# Using uv
uv run python main.py

# Or directly
python main.py

The server starts on http://0.0.0.0:8000 by default.

MCP Client Configuration

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "google-analytics": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Available Tools

Discovery Tools

Tool	Description
list_properties	List all accessible GA4 properties
get_property_details	Get property info (timezone, currency, etc.)
get_available_metrics	Get all dimensions/metrics for a property

Historical Report Tools

Tool	Description
run_custom_report	Flexible report with any dimensions/metrics
get_traffic_summary	Daily users, sessions, pageviews, bounce rate
get_acquisition_report	Traffic sources breakdown
get_page_performance	Top pages by pageviews
get_geographic_report	Users by country/city
get_device_report	Desktop/mobile/tablet breakdown
get_events_report	Top events by count
compare_periods	Period-over-period comparison

Realtime Tools

Tool	Description
get_realtime_overview	Current active users overview
get_realtime_pages	Currently active pages
get_realtime_traffic_sources	Current traffic sources
get_realtime_events	Events occurring now
run_custom_realtime_report	Custom realtime query

Admin Tools

Tool	Description
list_custom_dimensions	Property's custom dimensions
list_custom_metrics	Property's custom metrics

Example Usage (AI Agent)

1. list_properties()
   -> Discover all accessible GA4 properties

2. get_property_details("123456789")
   -> Get timezone, currency, and other property metadata

3. get_traffic_summary("123456789", "7daysAgo", "today")
   -> Get daily traffic metrics for the last week

4. get_acquisition_report("123456789", "yesterday", "yesterday")
   -> See where yesterday's traffic came from

5. compare_periods("123456789", "7daysAgo", "today", "14daysAgo", "8daysAgo")
   -> Compare this week to last week

6. get_realtime_overview("123456789")
   -> See who's on the site right now

Project Structure

google-analytics-mcp/
├── pyproject.toml          # Dependencies and build config
├── main.py                 # Server entry point
├── src/
│   ├── __init__.py
│   ├── config.py           # Environment variable settings
│   ├── clients/
│   │   ├── __init__.py
│   │   ├── admin_client.py # GA Admin API wrapper
│   │   └── data_client.py  # GA Data API wrapper
│   └── tools/
│       ├── __init__.py
│       ├── discovery.py    # Property discovery tools
│       ├── reports.py      # Historical report tools
│       ├── realtime.py     # Realtime data tools
│       └── admin.py        # Custom dimensions/metrics

License

MIT