our-claude-skills/ga-agent-project/docs/02-setup-guide.md

MCP Server Setup Guide

Step 1: Google Cloud Prerequisites

1.1 Create/Select Project

# 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

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

1.3 Create Service Account

# 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
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)

# 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

# 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

# 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):

{
  "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:

# 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

# 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

# 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