google-analytics-mcp


Namegoogle-analytics-mcp JSON
Version 1.2.0 PyPI version JSON
download
home_pageNone
SummaryGoogle 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.
upload_time2025-07-24 05:51:35
maintainerNone
docs_urlNone
authorNone
requires_python>=3.10
licenseMIT
keywords google-analytics mcp ai-assistant analytics ga4 claude cursor windsurf
VCS
bugtrack_url
requirements fastmcp google-analytics-data
Travis-CI No Travis.
coveralls test coverage No coveralls.
            <p align="center">
  <img src="logo.png" alt="Google Analytics MCP Logo" width="120" />


# Google Analytics MCP Server

[![PyPI version](https://badge.fury.io/py/google-analytics-mcp.svg)](https://badge.fury.io/py/google-analytics-mcp)
[![PyPI Downloads](https://static.pepy.tech/badge/google-analytics-mcp)](https://pepy.tech/projects/google-analytics-mcp)
[![GitHub stars](https://img.shields.io/github/stars/surendranb/google-analytics-mcp?style=social)](https://github.com/surendranb/google-analytics-mcp/stargazers)
[![GitHub forks](https://img.shields.io/github/forks/surendranb/google-analytics-mcp?style=social)](https://github.com/surendranb/google-analytics-mcp/network/members)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Made with Love](https://img.shields.io/badge/Made%20with-❤️-red.svg)](https://github.com/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](https://github.com/surendranb/google-search-console-mcp) that enables you to mix & match the data from both the sources

</p>
---

## Prerequisites

**Check your Python setup:**

```bash
# 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](https://console.cloud.google.com/)
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](https://analytics.google.com/)
   - 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](https://analytics.google.com/), 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:

```bash
pip install google-analytics-data
```

Create a test script (`test_ga4.py`):

```python
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:

```bash
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)

```bash
pip install google-analytics-mcp
```

**MCP Configuration:**

First, check your Python command:

```bash
python3 --version
python --version
```

Then use the appropriate configuration:

If `python3 --version` worked:

```json
{
  "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:

```json
{
  "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

```bash
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:**

```json
{
  "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

---

## 🚀 Performance Optimizations

This MCP server includes **built-in optimizations** to prevent context window crashes and ensure smooth operation:

### Smart Data Volume Management
- **Automatic row estimation** - Checks data volume before fetching
- **Interactive warnings** - Alerts when queries would return >2,500 rows
- **Optimization suggestions** - Provides specific recommendations to reduce data volume

### Server-Side Processing
- **Intelligent aggregation** - Automatically aggregates data when beneficial (e.g., totals across time periods)
- **Smart sorting** - Returns most relevant data first (recent dates, highest values)
- **Efficient filtering** - Leverages GA4's server-side filtering capabilities

### User Control Parameters
- `limit` - Set maximum number of rows to return
- `proceed_with_large_dataset=True` - Override warnings for large datasets
- `enable_aggregation=False` - Disable automatic aggregation
- `estimate_only=True` - Get row count estimates without fetching data

### Example: Handling Large Datasets
```python
# 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
```

---

## Available Tools

The server provides 5 main tools with **built-in optimization** to prevent context window crashes:

1. **`get_ga4_data`** - Retrieve GA4 data with custom dimensions and metrics
   - **Smart data volume warnings** - Alerts when queries would return >2,500 rows
   - **Server-side aggregation** - Automatically aggregates data when beneficial
   - **Intelligent sorting** - Returns most relevant data first
   - **User control parameters** - `limit`, `proceed_with_large_dataset`, `enable_aggregation`
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):**
```bash
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:**
```bash
# 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

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "google-analytics-mcp",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.10",
    "maintainer_email": null,
    "keywords": "google-analytics, mcp, ai-assistant, analytics, ga4, claude, cursor, windsurf",
    "author": null,
    "author_email": "Surendran B <reachsuren@gmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/77/21/ca7c07beaa5618d285b18d4933aabab9d72737e274aa28492b236d0eeb77/google_analytics_mcp-1.2.0.tar.gz",
    "platform": null,
    "description": "<p align=\"center\">\n  <img src=\"logo.png\" alt=\"Google Analytics MCP Logo\" width=\"120\" />\n\n\n# Google Analytics MCP Server\n\n[![PyPI version](https://badge.fury.io/py/google-analytics-mcp.svg)](https://badge.fury.io/py/google-analytics-mcp)\n[![PyPI Downloads](https://static.pepy.tech/badge/google-analytics-mcp)](https://pepy.tech/projects/google-analytics-mcp)\n[![GitHub stars](https://img.shields.io/github/stars/surendranb/google-analytics-mcp?style=social)](https://github.com/surendranb/google-analytics-mcp/stargazers)\n[![GitHub forks](https://img.shields.io/github/forks/surendranb/google-analytics-mcp?style=social)](https://github.com/surendranb/google-analytics-mcp/network/members)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Made with Love](https://img.shields.io/badge/Made%20with-\u2764\ufe0f-red.svg)](https://github.com/surendranb/google-analytics-mcp)\n\nConnect 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.\n\n**Compatible with:** Claude, Cursor and other MCP clients.\n\nI also built a [Google Search Console MCP](https://github.com/surendranb/google-search-console-mcp) that enables you to mix & match the data from both the sources\n\n</p>\n---\n\n## Prerequisites\n\n**Check your Python setup:**\n\n```bash\n# Check Python version (need 3.10+)\npython --version\npython3 --version\n\n# Check pip\npip --version\npip3 --version\n```\n\n**Required:**\n- Python 3.10 or higher\n- Google Analytics 4 property with data\n- Service account with Analytics Reporting API access\n\n---\n\n## Step 1: Setup Google Analytics Credentials\n\n### Create Service Account in Google Cloud Console\n\n1. Go to [Google Cloud Console](https://console.cloud.google.com/)\n2. **Create or select a project**:\n   - New project: Click \"New Project\" \u2192 Enter project name \u2192 Create\n   - Existing project: Select from dropdown\n3. **Enable the Analytics APIs**:\n   - Go to \"APIs & Services\" \u2192 \"Library\"\n   - Search for \"Google Analytics Reporting API\" \u2192 Click \"Enable\"\n   - Search for \"Google Analytics Data API\" \u2192 Click \"Enable\"\n4. **Create Service Account**:\n   - Go to \"APIs & Services\" \u2192 \"Credentials\"\n   - Click \"Create Credentials\" \u2192 \"Service Account\"\n   - Enter name (e.g., \"ga4-mcp-server\")\n   - Click \"Create and Continue\"\n   - Skip role assignment \u2192 Click \"Done\"\n5. **Download JSON Key**:\n   - Click your service account\n   - Go to \"Keys\" tab \u2192 \"Add Key\" \u2192 \"Create New Key\"\n   - Select \"JSON\" \u2192 Click \"Create\"\n   - Save the JSON file - you'll need its path\n\n### Add Service Account to GA4\n\n1. **Get service account email**:\n   - Open the JSON file\n   - Find the `client_email` field\n   - Copy the email (format: `ga4-mcp-server@your-project.iam.gserviceaccount.com`)\n2. **Add to GA4 property**:\n   - Go to [Google Analytics](https://analytics.google.com/)\n   - Select your GA4 property\n   - Click \"Admin\" (gear icon at bottom left)\n   - Under \"Property\" \u2192 Click \"Property access management\"\n   - Click \"+\" \u2192 \"Add users\"\n   - Paste the service account email\n   - Select \"Viewer\" role\n   - Uncheck \"Notify new users by email\"\n   - Click \"Add\"\n\n### Find Your GA4 Property ID\n\n1. In [Google Analytics](https://analytics.google.com/), select your property\n2. Click \"Admin\" (gear icon)\n3. Under \"Property\" \u2192 Click \"Property details\"\n4. Copy the **Property ID** (numeric, e.g., `123456789`)\n   - **Note**: This is different from the \"Measurement ID\" (starts with G-)\n\n### Test Your Setup (Optional)\n\nVerify your credentials:\n\n```bash\npip install google-analytics-data\n```\n\nCreate a test script (`test_ga4.py`):\n\n```python\nimport os\nfrom google.analytics.data_v1beta import BetaAnalyticsDataClient\n\n# Set credentials path\nos.environ[\"GOOGLE_APPLICATION_CREDENTIALS\"] = \"/path/to/your/service-account-key.json\"\n\n# Test connection\nclient = BetaAnalyticsDataClient()\nprint(\"\u2705 GA4 credentials working!\")\n```\n\nRun the test:\n\n```bash\npython test_ga4.py\n```\n\nIf you see \"\u2705 GA4 credentials working!\" you're ready to proceed.\n\n---\n\n## Step 2: Install the MCP Server\n\nChoose one method:\n\n### Method A: pip install (Recommended)\n\n```bash\npip install google-analytics-mcp\n```\n\n**MCP Configuration:**\n\nFirst, check your Python command:\n\n```bash\npython3 --version\npython --version\n```\n\nThen use the appropriate configuration:\n\nIf `python3 --version` worked:\n\n```json\n{\n  \"mcpServers\": {\n    \"ga4-analytics\": {\n      \"command\": \"python3\",\n      \"args\": [\"-m\", \"ga4_mcp_server\"],\n      \"env\": {\n        \"GOOGLE_APPLICATION_CREDENTIALS\": \"/path/to/your/service-account-key.json\",\n        \"GA4_PROPERTY_ID\": \"123456789\"\n      }\n    }\n  }\n}\n```\n\nIf `python --version` worked:\n\n```json\n{\n  \"mcpServers\": {\n    \"ga4-analytics\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"ga4_mcp_server\"],\n      \"env\": {\n        \"GOOGLE_APPLICATION_CREDENTIALS\": \"/path/to/your/service-account-key.json\",\n        \"GA4_PROPERTY_ID\": \"123456789\"\n      }\n    }\n  }\n}\n```\n\n### Method B: GitHub download\n\n```bash\ngit clone https://github.com/surendranb/google-analytics-mcp.git\ncd google-analytics-mcp\npython3 -m venv venv\nsource venv/bin/activate\npip install -r requirements.txt\n```\n\n**MCP Configuration:**\n\n```json\n{\n  \"mcpServers\": {\n    \"ga4-analytics\": {\n      \"command\": \"/full/path/to/ga4-mcp-server/venv/bin/python\",\n      \"args\": [\"/full/path/to/ga4-mcp-server/ga4_mcp_server.py\"],\n      \"env\": {\n        \"GOOGLE_APPLICATION_CREDENTIALS\": \"/path/to/your/service-account-key.json\",\n        \"GA4_PROPERTY_ID\": \"123456789\"\n      }\n    }\n  }\n}\n```\n\n---\n\n## Step 3: Update Configuration\n\n**Replace these placeholders in your MCP configuration:**\n- `/path/to/your/service-account-key.json` with your JSON file path\n- `123456789` with your GA4 Property ID\n- `/full/path/to/ga4-mcp-server/` with your download path (Method B only)\n\n---\n\n## Usage\n\nOnce configured, ask your MCP client questions like:\n\n### Discovery & Exploration\n- What GA4 dimension categories are available?\n- Show me all ecommerce metrics\n- What dimensions can I use for geographic analysis?\n\n### Traffic Analysis\n- What's my website traffic for the past week?\n- Show me user metrics by city for last month\n- Compare bounce rates between different date ranges\n\n### Multi-Dimensional Analysis\n- Show me revenue by country and device category for last 30 days\n- Analyze sessions and conversions by campaign and source/medium\n- Compare user engagement across different page paths and traffic sources\n\n### E-commerce Analysis\n- What are my top-performing products by revenue?\n- Show me conversion rates by traffic source and device type\n- Analyze purchase behavior by user demographics\n\n---\n\n## Quick Start Examples\n\nTry these example queries to see the MCP's analytical capabilities:\n\n### 1. Geographic Distribution\n```\nShow me a map of visitors by city for the last 30 days, with a breakdown of new vs returning users\n```\nThis demonstrates:\n- Geographic analysis\n- User segmentation\n- Time-based filtering\n- Data visualization\n\n### 2. User Behavior Analysis\n```\nCompare average session duration and pages per session by device category and browser over the last 90 days\n```\nThis demonstrates:\n- Multi-dimensional analysis\n- Time series comparison\n- User engagement metrics\n- Technology segmentation\n\n### 3. Traffic Source Performance\n```\nShow me conversion rates and revenue by traffic source and campaign, comparing last 30 days vs previous 30 days\n```\nThis demonstrates:\n- Marketing performance analysis\n- Period-over-period comparison\n- Conversion tracking\n- Revenue attribution\n\n### 4. Content Performance\n```\nWhat are my top 10 pages by engagement rate, and how has their performance changed over the last 3 months?\n```\nThis demonstrates:\n- Content analysis\n- Trend analysis\n- Engagement metrics\n- Ranking and sorting\n\n---\n\n## \ud83d\ude80 Performance Optimizations\n\nThis MCP server includes **built-in optimizations** to prevent context window crashes and ensure smooth operation:\n\n### Smart Data Volume Management\n- **Automatic row estimation** - Checks data volume before fetching\n- **Interactive warnings** - Alerts when queries would return >2,500 rows\n- **Optimization suggestions** - Provides specific recommendations to reduce data volume\n\n### Server-Side Processing\n- **Intelligent aggregation** - Automatically aggregates data when beneficial (e.g., totals across time periods)\n- **Smart sorting** - Returns most relevant data first (recent dates, highest values)\n- **Efficient filtering** - Leverages GA4's server-side filtering capabilities\n\n### User Control Parameters\n- `limit` - Set maximum number of rows to return\n- `proceed_with_large_dataset=True` - Override warnings for large datasets\n- `enable_aggregation=False` - Disable automatic aggregation\n- `estimate_only=True` - Get row count estimates without fetching data\n\n### Example: Handling Large Datasets\n```python\n# This query would normally return 2,605 rows and crash context window\nget_ga4_data(\n    dimensions=[\"date\", \"pagePath\", \"country\"],\n    date_range_start=\"90daysAgo\"\n)\n# Returns: {\"warning\": True, \"estimated_rows\": 2605, \"suggestions\": [...]}\n\n# Use monthly aggregation instead\nget_ga4_data(\n    dimensions=[\"month\", \"pagePath\", \"country\"], \n    date_range_start=\"90daysAgo\"\n)\n# Returns: Clean monthly data with manageable row count\n```\n\n---\n\n## Available Tools\n\nThe server provides 5 main tools with **built-in optimization** to prevent context window crashes:\n\n1. **`get_ga4_data`** - Retrieve GA4 data with custom dimensions and metrics\n   - **Smart data volume warnings** - Alerts when queries would return >2,500 rows\n   - **Server-side aggregation** - Automatically aggregates data when beneficial\n   - **Intelligent sorting** - Returns most relevant data first\n   - **User control parameters** - `limit`, `proceed_with_large_dataset`, `enable_aggregation`\n2. **`list_dimension_categories`** - Browse available dimension categories\n3. **`list_metric_categories`** - Browse available metric categories\n4. **`get_dimensions_by_category`** - Get dimensions for a specific category\n5. **`get_metrics_by_category`** - Get metrics for a specific category\n\n---\n\n## Dimensions & Metrics\n\nAccess to **200+ GA4 dimensions and metrics** organized by category:\n\n### Dimension Categories\n- **Time**: date, hour, month, year, etc.\n- **Geography**: country, city, region\n- **Technology**: browser, device, operating system\n- **Traffic Source**: campaign, source, medium, channel groups\n- **Content**: page paths, titles, content groups\n- **E-commerce**: item details, transaction info\n- **User Demographics**: age, gender, language\n- **Google Ads**: campaign, ad group, keyword data\n- And 10+ more categories\n\n### Metric Categories\n- **User Metrics**: totalUsers, newUsers, activeUsers\n- **Session Metrics**: sessions, bounceRate, engagementRate\n- **E-commerce**: totalRevenue, transactions, conversions\n- **Events**: eventCount, conversions, event values\n- **Advertising**: adRevenue, returnOnAdSpend\n- And more specialized metrics\n\n---\n\n## Troubleshooting\n\n**If you get \"No module named ga4_mcp_server\" (Method A):**\n```bash\npip3 install --user google-analytics-mcp\n```\n\n**If you get \"executable file not found\":**\n- Try the other Python command (`python` vs `python3`)\n- Use `pip3` instead of `pip` if needed\n\n**Permission errors:**\n```bash\n# Try user install instead of system-wide\npip install --user google-analytics-mcp\n```\n\n**Credentials not working:**\n1. **Verify the JSON file path** is correct and accessible\n2. **Check service account permissions**:\n   - Go to Google Cloud Console \u2192 IAM & Admin \u2192 IAM\n   - Find your service account \u2192 Check permissions\n3. **Verify GA4 access**:\n   - GA4 \u2192 Admin \u2192 Property access management\n   - Check for your service account email\n4. **Verify ID type**:\n   - Property ID: numeric (e.g., `123456789`) \u2705\n   - Measurement ID: starts with G- (e.g., `G-XXXXXXXXXX`) \u274c\n\n**API quota/rate limit errors:**\n- GA4 has daily quotas and rate limits\n- Try reducing the date range in your queries\n- Wait a few minutes between large requests\n\n---\n\n## Project Structure\n\n```\ngoogle-analytics-mcp/\n\u251c\u2500\u2500 ga4_mcp_server.py       # Main MCP server\n\u251c\u2500\u2500 ga4_dimensions.json     # All available GA4 dimensions\n\u251c\u2500\u2500 ga4_metrics.json        # All available GA4 metrics\n\u251c\u2500\u2500 requirements.txt        # Python dependencies\n\u251c\u2500\u2500 pyproject.toml          # Package configuration\n\u251c\u2500\u2500 README.md               # This file\n\u2514\u2500\u2500 claude-config-template.json  # MCP configuration template\n```\n\n---\n\n## License\n\nMIT License\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "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.",
    "version": "1.2.0",
    "project_urls": {
        "Homepage": "https://github.com/surendranb/google-analytics-mcp",
        "Issues": "https://github.com/surendranb/google-analytics-mcp/issues",
        "Repository": "https://github.com/surendranb/google-analytics-mcp"
    },
    "split_keywords": [
        "google-analytics",
        " mcp",
        " ai-assistant",
        " analytics",
        " ga4",
        " claude",
        " cursor",
        " windsurf"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "8de621e9942ad7f270889955910571e695dcbccb047c0b5246766c6f3c9837db",
                "md5": "7bd9f2bb2f08a5393140e566ec7d16d2",
                "sha256": "ccf0774fa7c5e26a8889adc602d2311b4f44038d1eb8ce19aa95e30a3abf81bd"
            },
            "downloads": -1,
            "filename": "google_analytics_mcp-1.2.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "7bd9f2bb2f08a5393140e566ec7d16d2",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.10",
            "size": 14396,
            "upload_time": "2025-07-24T05:51:34",
            "upload_time_iso_8601": "2025-07-24T05:51:34.075997Z",
            "url": "https://files.pythonhosted.org/packages/8d/e6/21e9942ad7f270889955910571e695dcbccb047c0b5246766c6f3c9837db/google_analytics_mcp-1.2.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "7721ca7c07beaa5618d285b18d4933aabab9d72737e274aa28492b236d0eeb77",
                "md5": "ea03a09a1f50e5c74f05ccc34e93b983",
                "sha256": "8a94d9e87e7fab239e469ff762af527e2d30bb61ac2f61b1edcd6ebcaaa74ff2"
            },
            "downloads": -1,
            "filename": "google_analytics_mcp-1.2.0.tar.gz",
            "has_sig": false,
            "md5_digest": "ea03a09a1f50e5c74f05ccc34e93b983",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.10",
            "size": 18685,
            "upload_time": "2025-07-24T05:51:35",
            "upload_time_iso_8601": "2025-07-24T05:51:35.754986Z",
            "url": "https://files.pythonhosted.org/packages/77/21/ca7c07beaa5618d285b18d4933aabab9d72737e274aa28492b236d0eeb77/google_analytics_mcp-1.2.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-07-24 05:51:35",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "surendranb",
    "github_project": "google-analytics-mcp",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "requirements": [
        {
            "name": "fastmcp",
            "specs": [
                [
                    ">=",
                    "2.0.0"
                ]
            ]
        },
        {
            "name": "google-analytics-data",
            "specs": [
                [
                    ">=",
                    "0.16.0"
                ]
            ]
        }
    ],
    "lcname": "google-analytics-mcp"
}
        
Elapsed time: 1.67410s