Andrew Yim
236be6c580
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
204 lines
4.3 KiB
Markdown
204 lines
4.3 KiB
Markdown
# 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
|