# MCP Servers Overview for GA Agent

## Available MCP Servers

### Google Analytics MCP Servers

| Server | Language | Source | Status |
|--------|----------|--------|--------|
| **google-analytics-mcp** (Official) | Python | [googleanalytics/google-analytics-mcp](https://github.com/googleanalytics/google-analytics-mcp) | Recommended |
| mcp-server-google-analytics | TypeScript | [ruchernchong/mcp-server-google-analytics](https://github.com/ruchernchong/mcp-server-google-analytics) | Community |

**Official Google GA MCP Features:**
- Real-time reporting
- Custom/standard dimensions/metrics
- Natural language queries (e.g., "top products by revenue")
- `order_by` support
- OAuth + Service Account auth

### BigQuery MCP Servers

| Server | Language | npm | Status |
|--------|----------|-----|--------|
| **@ergut/mcp-bigquery-server** | Node.js | `npx -y @ergut/mcp-bigquery-server` | Recommended |
| mcp-server-bigquery | Python | - | Alternative |
| Google MCP Toolbox | Python | - | Official (multi-DB) |

**ergut/mcp-bigquery-server Features:**
- Read-only secure access
- Schema discovery
- Natural language to SQL
- 1GB query limit

## Recommended Stack

For our GA Agent, we recommend:

```
┌─────────────────────────────────────────────────────┐
│                   Claude Code                        │
│                        │                             │
│           ┌───────────┴───────────┐                 │
│           ▼                       ▼                 │
│  ┌─────────────────┐    ┌─────────────────┐        │
│  │ Google Analytics│    │    BigQuery     │        │
│  │   MCP Server    │    │   MCP Server    │        │
│  └────────┬────────┘    └────────┬────────┘        │
│           │                      │                  │
│           ▼                      ▼                  │
│  ┌─────────────────┐    ┌─────────────────┐        │
│  │  GA4 Data API   │    │  BigQuery API   │        │
│  │  GA4 Admin API  │    │  (GA4 Export)   │        │
│  └─────────────────┘    └─────────────────┘        │
└─────────────────────────────────────────────────────┘
```

## Why Both?

1. **GA4 MCP** - Direct API access for:
   - Real-time data
   - Quick metrics queries
   - Account/property management

2. **BigQuery MCP** - For advanced analysis:
   - Historical data (GA4 → BigQuery export)
   - Complex SQL queries
   - Cross-dataset joins
   - Large-scale analysis

## Prerequisites

### Google Cloud Setup

1. Create a Google Cloud Project (or use existing)
2. Enable these APIs:
   - Google Analytics Data API
   - Google Analytics Admin API
   - BigQuery API

3. Create Service Account:
   - Go to IAM & Admin → Service Accounts
   - Create new service account
   - Grant roles:
     - `Analytics Viewer` (or Admin for write ops)
     - `BigQuery Data Viewer`
     - `BigQuery Job User`
   - Download JSON key file

4. Grant GA4 Access:
   - In GA4 Admin → Property Access Management
   - Add service account email with Viewer role

## Next Steps

See `02-setup-guide.md` for installation instructions.