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

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

• [x] Resolver Layer - Human-friendly ID resolution
• [x] TTL Caching - Performance optimization
• [x] Auto-retry - Resilient API calls
• [x] GMC Integration - Merchant Center tools
• [x] 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

---