directory changes and restructuring
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
203
ga-agent-skills/docs/02-setup-guide.md
Normal file
203
ga-agent-skills/docs/02-setup-guide.md
Normal file
@@ -0,0 +1,203 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user