Google Analytics

What is Google Analytics MCP Server?

Google Analytics MCP Server is a Python-based tool that allows Large Language Models (LLMs) like Claude and Cursor to access and analyze Google Analytics 4 (GA4) data using natural language. It provides access to over 200 GA4 dimensions and metrics, enabling users to query website traffic, user behavior, and analytics data conversationally.

How to use Google Analytics MCP Server?

To use the Google Analytics MCP Server, you need Python 3.10+ and a GA4 property with data. The setup involves:

1. Setting up Google Analytics Credentials: Create a service account in Google Cloud Console, enable the Google Analytics Reporting API and Google Analytics Data API, download the JSON key, and add the service account to your GA4 property with "Viewer" role. You also need to find your GA4 Property ID.
2. Installing the MCP Server: You can install it via pip (recommended) or by cloning the GitHub repository.
3. Updating MCP Configuration: Configure your MCP client (e.g., Claude, Cursor) with the appropriate command and environment variables, including the path to your service account key and your GA4 Property ID.

Once configured, you can ask your MCP client natural language questions to retrieve and analyze GA4 data.

Key Features of Google Analytics MCP Server

• Natural Language Querying: Access GA4 data using conversational language.
• Extensive Data Access: Supports over 200 GA4 dimensions and metrics.
• Compatibility: Works with Claude, Cursor, and other MCP clients.
• Data Exploration Tools: Provides tools to list dimension and metric categories, and retrieve dimensions/metrics by category.
• Five Main Tools: get_ga4_data, list_dimension_categories, list_metric_categories, get_dimensions_by_category, get_metrics_by_category.

Use Cases of Google Analytics MCP Server

• Discovery & Exploration: Understand available GA4 dimensions and metrics.
• Traffic Analysis: Query website traffic, user metrics by city, and compare bounce rates.
• Multi-Dimensional Analysis: Analyze revenue by country and device, sessions and conversions by campaign, and user engagement across page paths.
• E-commerce Analysis: Identify top-performing products, conversion rates by traffic source, and purchase behavior by demographics.
• Quick Start Examples: Geographic distribution analysis, user behavior analysis, traffic source performance, and content performance.

FAQ from Google Analytics MCP Server

Q: What if I get "No module named ga4_mcp_server"? A: Try pip3 install --user google-analytics-mcp.

Q: What if I get "executable file not found"? A: Try using the other Python command (python vs python3) or pip3 instead of pip.

Q: How to resolve permission errors? A: Try pip install --user google-analytics-mcp for user-specific installation.

Q: My credentials are not working. What should I do? A: Verify the JSON file path, check service account permissions in Google Cloud Console, ensure the service account has "Viewer" access in GA4, and confirm you are using the numeric GA4 Property ID (not the Measurement ID starting with G-).

Q: I am encountering API quota/rate limit errors. A: GA4 has daily quotas and rate limits. Try reducing the date range in your queries or wait a few minutes between large requests.

Google Analytics MCP Server

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

1. Go to Google Cloud Console
2. Create or select a project:
   • New project: Click "New Project" → Enter project name → Create
   • Existing project: Select from dropdown
3. 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"
4. 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"
5. 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

1. Get service account email:
   • Open the JSON file
   • Find the client_email field
   • Copy the email (format: ga4-mcp-server@your-project.iam.gserviceaccount.com)
2. 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

1. In Google Analytics, select your property
2. Click "Admin" (gear icon)
3. Under "Property" → Click "Property details"
4. 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

---

Available Tools

The server provides 5 main tools:

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

---

Dimensions & Metrics

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

Dimension Categories

• Time: date, hour, month, year, etc.
• Geography: country, city, region
• Technology: browser, device, operating system
• Traffic Source: campaign, source, medium, channel groups
• Content: page paths, titles, content groups
• E-commerce: item details, transaction info
• User Demographics: age, gender, language
• Google Ads: campaign, ad group, keyword data
• And 10+ more categories

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:

1. Verify the JSON file path is correct and accessible
2. Check service account permissions:
   • Go to Google Cloud Console → IAM & Admin → IAM
   • Find your service account → Check permissions
3. Verify GA4 access:
   • GA4 → Admin → Property access management
   • Check for your service account email
4. 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_server.py       # Main MCP server
├── ga4_dimensions.json     # All available GA4 dimensions
├── ga4_metrics.json        # All available GA4 metrics
├── requirements.txt        # Python dependencies
├── pyproject.toml          # Package configuration
├── README.md               # This file
└── claude-config-template.json  # MCP configuration template

---

License

MIT License