Google Analytics MCP Server

A powerful Model Context Protocol (MCP) server that provides comprehensive Google Analytics 4 (GA4), Google Search Console (GSC), and Google Merchant Center (GMC) integration for Claude Desktop and other MCP clients.

Key Features

49 Specialized Tools Across Google Platforms

• GA4: 20+ tools for reporting, admin, and discovery

• GSC: 10+ tools for search analytics and site management

• GMC: 11+ tools for merchant center and product management

• Resolver: 4 tools for human-friendly ID resolution

• Whoami: 1 unified summary tool

Smart Resolver Layer

• Human-friendly queries: Use domains like "gatedepot.com" instead of cryptic IDs

• Auto-resolution: Automatically finds the right property/site/account

• Fuzzy matching: Handles typos and variations intelligently

• Multi-platform: Works across GA4, GSC, and GMC

Performance Optimizations

• TTL Caching: 10-minute cache for discovery calls (instant repeat lookups)

• Auto-retry: Handles Google API rate limits with exponential backoff

• Configurable: Environment variables for cache and retry settings

Enterprise Security

• OAuth Integration: User-based authentication via Application Default Credentials

• Secret Management: Credentials stored securely in Google Secret Manager

• Read-only Access: Limited scopes for data protection

Related MCP server: Search Console MCP

Available Tools

GA4 Tools (20 tools)

Core Reporting:

• run_report - Custom GA4 reports with dimensions, metrics, filters

• run_realtime_report - Real-time analytics data

• get_custom_dimensions_and_metrics - Property metadata

Admin Management:

• get_account_summaries - List all GA4 accounts and properties

• get_property_details - Detailed property information

• list_conversion_events - Conversion event management

• list_data_streams - Data stream configuration

• list_custom_dimensions - Custom dimension management

• list_custom_metrics - Custom metric management

• list_google_ads_links - Google Ads integration

Enhanced Discovery:

• properties_list_accounts - Flattened account/property list

• properties_find - Search properties by name/URL

• datastreams_find - Find streams by URL/measurement ID

• report_top_pages - Top pages preset report

• report_revenue_by_channel - Revenue analysis preset

• report_events_over_time - Event tracking over time

• report_landing_pages_vs_conversions - Landing page analysis

GSC Tools (10 tools)

Basic Operations:

• gsc_sites_list - List Search Console sites

• gsc_sitemaps_list - Manage sitemaps

• gsc_search_analytics_query - Search performance data

Enhanced Analytics:

• sites_find - Find sites by domain/URL

• permissions_get - Site permission details

• top_queries - Top search queries preset

• top_pages - Top performing pages preset

• queries_for_page - Queries driving specific pages

• country_device_matrix - Geographic and device analysis

• sa_build_filters - Advanced filter builder

GMC Tools (11 tools)

Account Management:

• gmc_accounts_list - List Merchant Center accounts

• gmc_accounts_get - Account details

• gmc_accounts_issues_list - Account issues

• accounts_list - Enhanced account listing

• account_status - Account status and summary

Product Management:

• gmc_products_list - List products

• gmc_products_get - Product details

• products_find - Search products by query

• product_status - Individual product status

• product_status_aggregate - Bulk product status

Reporting:

• report_issues_last_30d - Recent issues report

Resolver Tools (4 tools)

• find_ga4_property - Resolve domain/URL to GA4 property

• find_gsc_site - Resolve domain/URL to GSC site

• find_gmc_account - Resolve domain/brand to GMC account

• find_google_ads_link - Find Google Ads links for properties

Whoami Tool (1 tool)

• summary - Unified overview of all accessible accounts and resources

🛠️ Quick Start

1. Clone and Setup

git clone https://github.com/pkidwell22/google-analytics-mcp.git
cd google-analytics-mcp
pip install -e .

2. Authentication Setup

# Run the OAuth setup script
./setup-oauth.sh

This will:

• Enable required Google APIs (GA4, GSC, GMC, Cloud Run, Secret Manager)

• Set up Application Default Credentials

• Configure OAuth scopes for all platforms

3. Local Testing

# Build and run with Docker
./test-local.sh

# Or run directly
python3 -m analytics_mcp.server --transport http --port 8080

4. Cloud Run Deployment

# Deploy to Google Cloud Run
./deploy.sh

🔧 Configuration

Claude Desktop Integration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "ga4-mcp": {
      "transport": {
        "type": "http",
        "url": "https://ga4-mcp-syiiroz2la-uc.a.run.app"
      },
      "env": {
        "GOOGLE_PROJECT_ID": "your-project-id"
      }
    }
  }
}

Environment Variables

• GOOGLE_PROJECT_ID: Your Google Cloud Project ID

• MCP_CACHE_TTL_SEC: Cache TTL in seconds (default: 600)

• MCP_CACHE_MAXSIZE: Maximum cache entries (default: 2048)

• MCP_GOOGLE_RETRIES: API retry attempts (default: 5)

Example Usage

With Claude Desktop

Natural Language Queries:

• "Show me revenue by channel for gatedepot.com"

• "What are the top pages for my site?"

• "Find conversion issues in my Merchant Center"

• "List all my Google properties and accounts"

• "Show me search performance for my landing pages"

Advanced Analytics:

• "Get top queries driving traffic to /products page"

• "Show me country and device breakdown for last month"

• "Find products with issues in my Merchant Center"

• "Analyze events over time for purchase events"

Direct API Usage

# Health check
curl https://ga4-mcp-syiiroz2la-uc.a.run.app/health

# Test cache functionality
bash scripts/smoke_cache.sh

Architecture

analytics_mcp/
├── coordinator.py              # MCP server configuration
├── server.py                  # Entry point and transport handling
├── tools/
│   ├── utils.py               # Common utilities and auth
│   ├── reporting/             # GA4 Data API tools
│   ├── admin/                 # GA4 Admin API tools
│   ├── gsc.py                 # Google Search Console tools
│   ├── gsc_enhanced.py        # Enhanced GSC tools
│   ├── gmc.py                 # Google Merchant Center tools
│   ├── gmc_enhanced.py        # Enhanced GMC tools
│   ├── ga4_enhanced.py        # Enhanced GA4 tools
│   ├── resolver.py            # Human-friendly ID resolution
│   └── whoami.py              # Unified account summary
├── utils/
│   ├── cache.py               # TTL caching system
│   └── google_retry.py        # API retry logic
└── scripts/
    └── smoke_cache.sh         # Cache validation script

Security

• OAuth Integration: User-based authentication via Application Default Credentials

• Secret Management: Credentials stored securely in Google Secret Manager

• Read-only Access: Limited scopes for data protection

• No Hardcoded Keys: All sensitive data externalized

• Environment-based Config: Secure configuration via environment variables

Performance Features

Smart Caching

• TTL-based: Configurable cache expiration (default: 10 minutes)

• Memory efficient: LRU eviction with configurable max size

• Transparent: Cache status visible in meta.cached field

• Selective: Only caches discovery/resolver calls, not real-time data

Resilient API Calls

• Auto-retry: Handles 429/5xx errors automatically

• Exponential backoff: Prevents API hammering

• Random jitter: Avoids thundering herd problems

• Configurable: Adjustable retry attempts and timing

Testing

Local Testing

# Run server locally
python3 -m analytics_mcp.server --transport http --port 8080

# Test specific tools
python3 -c "
import asyncio
from analytics_mcp.tools.resolver import find_ga4_property
# Test your tool here
"

Cache Testing

# Test cache functionality
bash scripts/smoke_cache.sh

# Test with custom URL
URL=https://your-service-url.run.app bash scripts/smoke_cache.sh

Real-World Impact

Before MCP:

• Copy/paste property IDs like properties/341922028

• Switch between multiple Google tools

• Remember different interfaces and APIs

• Manual ID lookups and context switching

After MCP:

• Natural language: "Show me revenue for gatedepot.com"

• Unified interface through Claude

• Instant cached lookups

• Automatic error handling and retries

Deployment Scripts

• setup-oauth.sh - Initial OAuth setup and API enablement

• test-local.sh - Local Docker testing

• deploy.sh - Cloud Run deployment with environment variables

• test-mcp.sh - MCP server testing

• scripts/smoke_cache.sh - Cache validation testing

Prerequisites

• Python 3.10+

• Google Cloud Project with billing enabled

• Google Analytics 4 property

• Google Search Console access (optional)

• Google Merchant Center access (optional)

• Docker (for local testing)

• gcloud CLI configured

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests

5. Submit a pull request

License

Apache 2.0 - See LICENSE file for details

Support

• Issues: GitHub Issues

• Documentation: See README_mcp_claude.md for Claude Desktop setup

• Deployment: See DEPLOYMENT_STEPS.md for detailed deployment guide

Roadmap

• Resolver Layer - Human-friendly ID resolution

• TTL Caching - Performance optimization

• Auto-retry - Resilient API calls

• GMC Integration - Merchant Center tools

• Enhanced Tools - Discovery and preset reports

• URL Inspection API - GSC URL inspection

• Batch Operations - Bulk data operations

• Custom Dashboards - Visualization tools

• Export Functionality - Data export capabilities

• Advanced Filtering - More sophisticated query options