# GA4 MCP Server

A Model Context Protocol server that connects Claude to Google Analytics 4, enabling natural language queries of your website analytics data.

## Features

- **get_traffic_summary** — Sessions, users, page views, bounce rate, avg session duration
- **get_top_pages** — Most visited pages with engagement metrics
- **get_traffic_sources** — Traffic breakdown by source (organic, direct, referral, etc.)
- **get_user_engagement** — Engaged sessions, bounce rate, screen counts per session

## Quick Start

### 1. Install Dependencies

```bash
npm install
```

### 2. Set Up Credentials

1. Copy the GA4 service account JSON file you downloaded to this folder:
   ```bash
   cp ~/Downloads/app-coaching-ga4-73c82846b5b0.json ./credentials.json
   ```

2. Create a `.env` file:
   ```bash
   cp .env.example .env
   ```

3. Update `.env` with your GA4 Property ID:
   ```
   GA4_CREDENTIALS_PATH=./credentials.json
   GA4_PROPERTY_ID=544866887
   ```

### 3. Add Service Account to GA4

In Google Analytics:
1. Go to Admin → Property Access Management
2. Click **+** (Add user)
3. Paste: `ga4-mcp-server@app-coaching-ga4.iam.gserviceaccount.com`
4. Assign **Viewer** role
5. Save

### 4. Build & Test

```bash
npm run build
npm run dev
```

You should see: `GA4 MCP Server started`

### 5. Test with MCP Inspector

In a new terminal:
```bash
npm run inspect
```

This opens an interactive tool to test the server. Try:
- **Tool:** `get_traffic_summary`
- **Inputs:**
  - propertyId: `544866887`
  - startDate: `2026-07-01`
  - endDate: `2026-07-10`

## Deployment Options

### Option 1: Replit (Easiest)

1. Create a new Replit
2. Import from GitHub (clone this repo) or upload files
3. Set environment variables in Replit Secrets:
   - `GA4_CREDENTIALS_PATH=./credentials.json`
4. Upload `credentials.json` to Replit
5. Run: `npm install && npm run build && npm run dev`
6. Replit gives you a live URL
7. Connect to Claude using that URL

### Option 2: Railway

1. Create a Railway project
2. Upload this repo via GitHub
3. Add `credentials.json` as a config file
4. Set env var: `GA4_CREDENTIALS_PATH=./credentials.json`
5. Deploy
6. Get the URL from Railway
7. Connect to Claude

### Option 3: Local (for testing only)

Run `npm run dev` locally, then in Claude's MCP settings add:
```json
{
  "name": "ga4-mcp",
  "type": "stdio",
  "command": "node",
  "args": ["dist/index.js"]
}
```

## Usage in Claude

Once deployed, ask Claude things like:

- "What's the traffic summary for appcoaching.io for the last 7 days?"
- "Which pages on my site get the most traffic?"
- "What's driving traffic to appcoaching.io? Organic or direct?"
- "What's the engagement rate on my site?"

Claude will automatically call the appropriate GA4 tools and analyze the data.

## Troubleshooting

**"Credentials file not found"**
- Ensure `credentials.json` is in the project root
- Check `GA4_CREDENTIALS_PATH` env var is set correctly

**"Unauthorized" or "Permission denied"**
- Verify the service account email is added to GA4 with Viewer role
- Check that the correct Property ID is being used (544866887)

**"No data available"**
- Ensure the date range has actual GA4 data
- GA4 can take 24-48 hours to start collecting data on a new property

## Files

- `src/index.ts` — Main MCP server implementation
- `package.json` — Dependencies and scripts
- `tsconfig.json` — TypeScript configuration
- `credentials.json` — GA4 service account (keep secure!)

## Security

**Never commit `credentials.json` to GitHub.** Add to `.gitignore`:
```
credentials.json
.env
node_modules/
dist/
```

The credentials file is sensitive—treat it like a password.