google-analytics-mcp 1.0.0__py3-none-any.whl

ga4_mcp_server.py

@@ -0,0 +1,236 @@
+from fastmcp import FastMCP
+from google.analytics.data_v1beta import BetaAnalyticsDataClient
+from google.analytics.data_v1beta.types import (
+    DateRange, Dimension, Metric, RunReportRequest
+)
+import os
+import sys
+import json
+from pathlib import Path
+
+# Configuration from environment variables
+CREDENTIALS_PATH = os.getenv("GOOGLE_APPLICATION_CREDENTIALS")
+GA4_PROPERTY_ID = os.getenv("GA4_PROPERTY_ID")
+
+# Validate required environment variables
+if not CREDENTIALS_PATH:
+    print("ERROR: GOOGLE_APPLICATION_CREDENTIALS environment variable not set", file=sys.stderr)
+    print("Please set it to the path of your service account JSON file", file=sys.stderr)
+    sys.exit(1)
+
+if not GA4_PROPERTY_ID:
+    print("ERROR: GA4_PROPERTY_ID environment variable not set", file=sys.stderr)
+    print("Please set it to your GA4 property ID (e.g., 123456789)", file=sys.stderr)
+    sys.exit(1)
+
+# Validate credentials file exists
+if not os.path.exists(CREDENTIALS_PATH):
+    print(f"ERROR: Credentials file not found: {CREDENTIALS_PATH}", file=sys.stderr)
+    print("Please check the GOOGLE_APPLICATION_CREDENTIALS path", file=sys.stderr)
+    sys.exit(1)
+
+# Initialize FastMCP
+mcp = FastMCP("Google Analytics 4")
+
+# Load dimensions and metrics from JSON files
+def load_dimensions():
+    """Load available dimensions from JSON file"""
+    try:
+        script_dir = Path(__file__).parent
+        with open(script_dir / "ga4_dimensions.json", "r") as f:
+            return json.load(f)
+    except FileNotFoundError:
+        print("Warning: ga4_dimensions.json not found", file=sys.stderr)
+        return {}
+
+def load_metrics():
+    """Load available metrics from JSON file"""
+    try:
+        script_dir = Path(__file__).parent
+        with open(script_dir / "ga4_metrics.json", "r") as f:
+            return json.load(f)
+    except FileNotFoundError:
+        print("Warning: ga4_metrics.json not found", file=sys.stderr)
+        return {}
+
+@mcp.tool()
+def list_dimension_categories():
+    """
+    List all available GA4 dimension categories with descriptions.
+    
+    Returns:
+        Dictionary of dimension categories and their available dimensions.
+    """
+    dimensions = load_dimensions()
+    result = {}
+    for category, dims in dimensions.items():
+        result[category] = {
+            "count": len(dims),
+            "dimensions": list(dims.keys())
+        }
+    return result
+
+@mcp.tool()
+def list_metric_categories():
+    """
+    List all available GA4 metric categories with descriptions.
+    
+    Returns:
+        Dictionary of metric categories and their available metrics.
+    """
+    metrics = load_metrics()
+    result = {}
+    for category, mets in metrics.items():
+        result[category] = {
+            "count": len(mets),
+            "metrics": list(mets.keys())
+        }
+    return result
+
+@mcp.tool()
+def get_dimensions_by_category(category):
+    """
+    Get all dimensions in a specific category with their descriptions.
+    
+    Args:
+        category: Category name (e.g., 'time', 'geography', 'ecommerce')
+        
+    Returns:
+        Dictionary of dimensions and their descriptions for the category.
+    """
+    dimensions = load_dimensions()
+    if category in dimensions:
+        return dimensions[category]
+    else:
+        available_categories = list(dimensions.keys())
+        return {"error": f"Category '{category}' not found. Available categories: {available_categories}"}
+
+@mcp.tool()
+def get_metrics_by_category(category):
+    """
+    Get all metrics in a specific category with their descriptions.
+    
+    Args:
+        category: Category name (e.g., 'user_metrics', 'ecommerce_metrics', 'session_metrics')
+        
+    Returns:
+        Dictionary of metrics and their descriptions for the category.
+    """
+    metrics = load_metrics()
+    if category in metrics:
+        return metrics[category]
+    else:
+        available_categories = list(metrics.keys())
+        return {"error": f"Category '{category}' not found. Available categories: {available_categories}"}
+
+@mcp.tool()
+def get_ga4_data(
+    dimensions=["date"],
+    metrics=["totalUsers", "newUsers", "bounceRate", "screenPageViewsPerSession", "averageSessionDuration"],
+    date_range_start="7daysAgo",
+    date_range_end="yesterday"
+):
+    """
+    Retrieve GA4 metrics data broken down by the specified dimensions.
+    
+    Args:
+        dimensions: List of GA4 dimensions (e.g., ["date", "city"]) or a string 
+                    representation (e.g., "[\"date\", \"city\"]" or "date,city").
+        metrics: List of GA4 metrics (e.g., ["totalUsers", "newUsers"]) or a string
+                 representation (e.g., "[\"totalUsers\"]" or "totalUsers,newUsers").
+        date_range_start: Start date in YYYY-MM-DD format or relative date like '7daysAgo'.
+        date_range_end: End date in YYYY-MM-DD format or relative date like 'yesterday'.
+        
+    Returns:
+        List of dictionaries containing the requested data, or an error dictionary.
+    """
+    try:
+        # Handle cases where dimensions might be passed as a string from the MCP client
+        parsed_dimensions = dimensions
+        if isinstance(dimensions, str):
+            try:
+                # Attempt to parse as JSON array first (e.g., "[\"date\", \"city\"]")
+                parsed_dimensions = json.loads(dimensions)
+                # Ensure it's a list after parsing; if json.loads gives a single string, wrap it in a list
+                if not isinstance(parsed_dimensions, list):
+                    parsed_dimensions = [str(parsed_dimensions)]
+            except json.JSONDecodeError:
+                # If not a valid JSON string, treat as comma-separated (e.g., "date,city" or "date")
+                parsed_dimensions = [d.strip() for d in dimensions.split(',')]
+        
+        # Ensure all elements are non-empty strings after potential parsing
+        parsed_dimensions = [str(d).strip() for d in parsed_dimensions if str(d).strip()]
+
+        # Handle cases where metrics might be passed as a string
+        parsed_metrics = metrics
+        if isinstance(metrics, str):
+            try:
+                parsed_metrics = json.loads(metrics)
+                if not isinstance(parsed_metrics, list):
+                     parsed_metrics = [str(parsed_metrics)]
+            except json.JSONDecodeError:
+                parsed_metrics = [m.strip() for m in metrics.split(',')]
+        
+        parsed_metrics = [str(m).strip() for m in parsed_metrics if str(m).strip()]
+
+        # Proceed if we have valid dimensions and metrics after parsing
+        if not parsed_dimensions:
+            return {"error": "Dimensions list cannot be empty after parsing."}
+        if not parsed_metrics:
+            return {"error": "Metrics list cannot be empty after parsing."}
+
+        # GA4 API Call
+        client = BetaAnalyticsDataClient()
+        
+        # Convert dimensions and metrics to GA4 API format
+        dimension_objects = [Dimension(name=d) for d in parsed_dimensions]
+        metric_objects = [Metric(name=m) for m in parsed_metrics]
+        
+        # Build the request
+        request = RunReportRequest(
+            property=f"properties/{GA4_PROPERTY_ID}",
+            dimensions=dimension_objects,
+            metrics=metric_objects,
+            date_ranges=[DateRange(start_date=date_range_start, end_date=date_range_end)]
+        )
+        
+        # Execute the request
+        response = client.run_report(request)
+        
+        # Format the response into a more usable structure
+        result = []
+        for row_idx, row in enumerate(response.rows):
+            data_row = {}
+            
+            # Extract dimension values
+            for i, dimension_header in enumerate(response.dimension_headers):
+                # Check if dimension_values has enough elements
+                if i < len(row.dimension_values):
+                    data_row[dimension_header.name] = row.dimension_values[i].value
+                else:
+                    data_row[dimension_header.name] = None
+                
+            # Extract metric values
+            for i, metric_header in enumerate(response.metric_headers):
+                 # Check if metric_values has enough elements
+                if i < len(row.metric_values):
+                    data_row[metric_header.name] = row.metric_values[i].value
+                else:
+                    data_row[metric_header.name] = None
+                    
+            result.append(data_row)
+        
+        return result
+    except Exception as e:
+        error_message = f"Error fetching GA4 data: {str(e)}"
+        print(error_message, file=sys.stderr)
+        # Include more details if available, e.g. from e.details() for gRPC errors
+        if hasattr(e, 'details'):
+            error_message += f" Details: {e.details()}"
+        return {"error": error_message}
+
+# Start the server when run directly
+if __name__ == "__main__":
+    # Use stdio transport ONLY - this is critical for MCP with Claude
+    print("Starting GA4 MCP server...", file=sys.stderr)
+    mcp.run(transport="stdio")

google_analytics_mcp-1.0.0.dist-info/METADATA

@@ -0,0 +1,299 @@
+Metadata-Version: 2.4
+Name: google-analytics-mcp
+Version: 1.0.0
+Summary: Google Analytics 4 MCP Server for Claude, Cursor, Windsurf etc
+Author-email: Surendran Balakrishnan <surendran.balakrishnan@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/surendranb/google-analytics-mcp
+Project-URL: Repository, https://github.com/surendranb/google-analytics-mcp
+Project-URL: Issues, https://github.com/surendranb/google-analytics-mcp/issues
+Keywords: google-analytics,mcp,claude,ai,analytics,ga4
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: fastmcp>=0.1.0
+Requires-Dist: google-analytics-data>=0.16.0
+
+# Google Analytics MCP Server for Claude
+
+Connect Google Analytics 4 data directly to Claude AI conversations. Ask questions about your website traffic, user behavior, and analytics data in natural language with access to 200+ GA4 dimensions and metrics.
+
+## Prerequisites
+
+**Check your Python setup first:**
+
+```bash
+# Check Python version (need 3.8+)
+python --version
+python3 --version
+
+# Check pip
+pip --version
+pip3 --version
+```
+
+**What you need:**
+- Python 3.8 or higher
+- Google Analytics 4 property with data
+- Service account with Analytics Reporting API access
+
+## Installation
+
+Choose either route:
+
+### Route 1: pip install (Recommended)
+
+```bash
+pip install google-analytics-mcp
+```
+
+### Route 2: GitHub download
+
+```bash
+git clone https://github.com/surendranb/google-analytics-mcp.git
+cd google-analytics-mcp
+pip install -r requirements.txt
+```
+
+## Setup
+
+### Step 1: Get GA4 Credentials
+
+**Part A: Create Service Account in Google Cloud Console**
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. **Create or select a project**:
+   - If new: Click "New Project" → Enter project name → Create
+   - If existing: Select your project from the dropdown
+3. **Enable the Analytics Reporting API**:
+   - Go to "APIs & Services" → "Library"
+   - Search for "Google Analytics Reporting API"
+   - Click on it → Click "Enable"
+4. **Enable the Analytics Data API**:
+   - Search for "Google Analytics Data API" 
+   - Click on it → Click "Enable"
+5. **Create Service Account**:
+   - Go to "APIs & Services" → "Credentials"
+   - Click "Create Credentials" → "Service Account"
+   - Enter a name (e.g., "ga4-mcp-server")
+   - Click "Create and Continue"
+   - Skip role assignment for now → Click "Done"
+6. **Download JSON Key**:
+   - Click on your newly created service account
+   - Go to "Keys" tab → "Add Key" → "Create New Key"
+   - Select "JSON" → Click "Create"
+   - **Save this file securely** - you'll need the path to it
+
+**Part B: Add Service Account to GA4**
+
+1. **Copy the service account email**:
+   - From the downloaded JSON file, find the `client_email` field
+   - Copy this email address (looks like: `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 in bottom left)
+   - Under "Property" column → Click "Property access management"
+   - Click "+" → "Add users"
+   - Paste the service account email
+   - Select "Viewer" role (sufficient for reading data)
+   - Uncheck "Notify new users by email"
+   - Click "Add"
+
+### Step 2: Find Your GA4 Property ID
+
+1. In [Google Analytics](https://analytics.google.com/), select your property
+2. Click "Admin" (gear icon)
+3. Under "Property" column → Click "Property details" 
+4. Copy the **Property ID** (numeric, e.g., `1234567890`)
+   - **Note**: This is different from the "Measurement ID" (starts with G-)
+
+### Step 3: Test Your Setup (Optional)
+
+Before configuring Claude, verify your credentials work:
+
+1. **Install Google Analytics Data library**:
+   ```bash
+   pip install google-analytics-data
+   ```
+
+2. **Test script** (save as `test_ga4.py`):
+   ```python
+   import os
+   from google.analytics.data_v1beta import BetaAnalyticsDataClient
+   
+   # Set your credentials
+   os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = "/path/to/your/service-account-key.json"
+   
+   # Test connection
+   client = BetaAnalyticsDataClient()
+   print("✅ GA4 credentials working!")
+   ```
+
+3. **Run test**:
+   ```bash
+   python test_ga4.py
+   ```
+
+If you see "✅ GA4 credentials working!" you're ready to proceed.
+
+### Step 4: Configure Claude
+
+Add this to your Claude MCP configuration:
+
+**For Route 1 (pip install):**
+```json
+{
+  "mcpServers": {
+    "ga4-analytics": {
+      "command": "ga4-mcp-server",
+      "env": {
+        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json",
+        "GA4_PROPERTY_ID": "346085905"
+      }
+    }
+  }
+}
+```
+
+**For Route 2 (GitHub download):**
+```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": "346085905"
+      }
+    }
+  }
+}
+```
+
+**Replace:**
+- `/path/to/your/service-account-key.json` with your actual credential file path
+- `346085905` with your actual GA4 Property ID
+- `/path/to/ga4-mcp-server/` with your actual download path (Route 2 only)
+
+## Usage
+
+Once configured, ask Claude 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"
+
+## 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
+
+### Command not found (Route 1)
+If `google-analytics-mcp` command not found, try:
+```json
+{
+  "command": "python3",
+  "args": ["-m", "ga4_mcp_server"]
+}
+```
+
+### Python version issues
+- Use `python3` instead of `python` if you have both Python 2 and 3
+- 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 that the service account has Analytics Reporting API access**:
+   - Go to Google Cloud Console → IAM & Admin → IAM
+   - Find your service account → Check it has necessary permissions
+3. **Ensure the service account email is added as a viewer in GA4**:
+   - GA4 → Admin → Property access management
+   - Look for your service account email in the list
+4. **Verify you're using the Property ID, not Measurement ID**:
+   - Property ID: numeric (e.g., `1234567890`) ✅
+   - 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

google_analytics_mcp-1.0.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+ga4_mcp_server.py,sha256=NZaj0Uu49ORRLAnieKBDN50F5tECpjp5R3YKAl1ithA,9040
+google_analytics_mcp-1.0.0.dist-info/METADATA,sha256=p6bZhBG-UycziKXbd0GFHrLQwoI5U-k5SeDn0TQLPZI,9577
+google_analytics_mcp-1.0.0.dist-info/WHEEL,sha256=zaaOINJESkSfm_4HQVc5ssNzHCPXhJm0kEUakpsEHaU,91
+google_analytics_mcp-1.0.0.dist-info/entry_points.txt,sha256=FxiRVVgKqoXvfu9vxgborulOKJibcsIQ0YLomlNbMCQ,61
+google_analytics_mcp-1.0.0.dist-info/top_level.txt,sha256=nhVl9yD14a_BIFxv0qrslrX6lzGr3h40ifIGlLR2xFg,15
+google_analytics_mcp-1.0.0.dist-info/RECORD,,

google_analytics_mcp-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.8.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

google_analytics_mcp-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+google-analytics-mcp = ga4_mcp_server:main

google_analytics_mcp-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ga4_mcp_server