# MCP Server Setup Guide

## Step 1: Google Cloud Prerequisites

### 1.1 Create/Select Project

```bash
# List existing projects
gcloud projects list

# Create new project (optional)
gcloud projects create ga-agent-project --name="GA Agent Project"

# Set active project
gcloud config set project YOUR_PROJECT_ID
```

### 1.2 Enable Required APIs

```bash
# Enable all required APIs
gcloud services enable \
  analyticsdata.googleapis.com \
  analyticsadmin.googleapis.com \
  bigquery.googleapis.com
```

### 1.3 Create Service Account

```bash
# Create service account
gcloud iam service-accounts create ga-agent-sa \
  --display-name="GA Agent Service Account"

# Get the email
SA_EMAIL="ga-agent-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com"

# Grant BigQuery roles
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:$SA_EMAIL" \
  --role="roles/bigquery.dataViewer"

gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:$SA_EMAIL" \
  --role="roles/bigquery.jobUser"

# Create and download key
gcloud iam service-accounts keys create \
  ~/ga-agent-credentials.json \
  --iam-account=$SA_EMAIL

# Move to secure location
mv ~/ga-agent-credentials.json /path/to/secure/location/
```

### 1.4 Grant GA4 Property Access

1. Go to [Google Analytics Admin](https://analytics.google.com/analytics/web/)
2. Select your property
3. Admin → Property Access Management
4. Click "+" → Add users
5. Enter service account email: `ga-agent-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com`
6. Select role: **Viewer** (or Analyst for more access)

---

## Step 2: Install Google Analytics MCP Server

### Option A: Official Google GA MCP (Python)

```bash
# Clone the repository
git clone https://github.com/googleanalytics/google-analytics-mcp.git
cd google-analytics-mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e .

# Set credentials
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/ga-agent-credentials.json"

# Test the server
python -m google_analytics_mcp
```

### Option B: TypeScript Community Server

```bash
# Install globally
npm install -g @anthropic/mcp-server-google-analytics

# Or run with npx
npx @anthropic/mcp-server-google-analytics
```

---

## Step 3: Install BigQuery MCP Server

```bash
# Using npx (recommended - no install needed)
npx -y @ergut/mcp-bigquery-server \
  --project-id YOUR_PROJECT_ID \
  --location us-central1 \
  --key-file /path/to/ga-agent-credentials.json

# Or install globally
npm install -g @ergut/mcp-bigquery-server
```

---

## Step 4: Configure Claude Code

Add to your Claude Code MCP configuration (`~/.claude/mcp_servers.json` or project `.mcp.json`):

```json
{
  "mcpServers": {
    "google-analytics": {
      "command": "python",
      "args": ["-m", "google_analytics_mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/ga-agent-credentials.json"
      }
    },
    "bigquery": {
      "command": "npx",
      "args": [
        "-y",
        "@ergut/mcp-bigquery-server",
        "--project-id", "YOUR_PROJECT_ID",
        "--location", "us-central1",
        "--key-file", "/path/to/ga-agent-credentials.json"
      ]
    }
  }
}
```

---

## Step 5: Verify Installation

After restarting Claude Code:

```bash
# Check servers are connected
mcp-cli servers

# List available tools
mcp-cli tools google-analytics
mcp-cli tools bigquery
```

Expected output should show tools like:
- `google-analytics/run_report`
- `google-analytics/run_realtime_report`
- `bigquery/execute-query`
- `bigquery/list-tables`

---

## Troubleshooting

### Authentication Errors

```bash
# Verify credentials
gcloud auth application-default print-access-token

# Check service account permissions
gcloud projects get-iam-policy YOUR_PROJECT_ID \
  --filter="bindings.members:ga-agent-sa"
```

### GA4 Access Issues

- Ensure service account email is added to GA4 property
- Wait 5-10 minutes after adding access
- Check property ID is correct (numeric, not "UA-" format)

### BigQuery Connection Issues

```bash
# Test BigQuery access directly
bq ls YOUR_PROJECT_ID:analytics_*

# Check dataset exists
bq show YOUR_PROJECT_ID:analytics_PROPERTY_ID
```

---

## Next Steps

1. Set up GA4 → BigQuery export (if not already)
2. Create visualization tools (see `03-visualization-setup.md`)
3. Build the Claude Skill