# GA4 MCP Server

A Model Context Protocol (MCP) server for Google Analytics 4 (GA4) that provides tools for querying GA4 data through the Admin API and Data API.

## Features

- **Dual Authentication**: Supports both OAuth Playground tokens and Service Account credentials
- **8 GA4 Tools**:
  - Account and property management (Admin API)
  - Report execution and realtime data (Data API)
  - **GTM → GA4 parameter validation** (cross-platform orchestration)
- **Compatible with Claude Desktop** and other MCP-enabled clients
- **GTM Integration**: Works with GTM MCP Server for end-to-end event validation

## Installation

```bash
npm install
npm run build
```

## Quick Start (OAuth Setup)

### 1. Create OAuth Credentials

1. Go to [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
2. Create a new project or select an existing one
3. Enable the **Google Analytics Data API** and **Google Analytics Admin API**
4. Go to **Credentials** → **Create Credentials** → **OAuth client ID**
5. Select **Desktop app** as the application type
6. Download or copy the Client ID and Client Secret

### 2. Run Setup Script

```bash
# Set your OAuth credentials
export GA4_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GA4_CLIENT_SECRET="your-client-secret"

# Run setup to authenticate with Google
npm run setup
```

This will:
- Open a browser for Google login
- Request read-only access to Google Analytics
- Save tokens to `~/.ga4-mcp/tokens.json`

### 3. Use the Server

Once authenticated, you can use the MCP server with Claude Desktop or other clients.

## Authentication

The server supports two authentication methods, checked in this order:

### 1. OAuth Playground Tokens (Recommended for personal use)

Set these environment variables:
- `GA4_ACCESS_TOKEN` - OAuth access token
- `GA4_REFRESH_TOKEN` - OAuth refresh token
- `GA4_CLIENT_ID` - OAuth client ID
- `GA4_CLIENT_SECRET` - OAuth client secret

Or create `~/.ga4-mcp/tokens.json`:
```json
{
  "access_token": "your-access-token",
  "refresh_token": "your-refresh-token",
  "client_id": "your-client-id",
  "client_secret": "your-client-secret"
}
```

### 2. Service Account (Recommended for production)

Options (in priority order):
1. Set `GA4_SERVICE_ACCOUNT_JSON` environment variable with JSON string
2. Set `GOOGLE_APPLICATION_CREDENTIALS` to the JSON file path
3. Place JSON file at `~/.ga4-mcp/credentials.json`
4. Place JSON file in `./Credential/` folder

## Usage

### Claude Desktop Configuration

Add to your Claude Desktop configuration (`~/.config/claude-desktop/config.json`):

```json
{
  "mcpServers": {
    "ga4": {
      "command": "node",
      "args": ["/path/to/ga4-mcp-server/dist/index.js"],
      "env": {
        "GA4_ACCESS_TOKEN": "your-access-token",
        "GA4_REFRESH_TOKEN": "your-refresh-token",
        "GA4_CLIENT_ID": "your-client-id",
        "GA4_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}
```

### Direct Execution

```bash
# With OAuth environment variables
GA4_ACCESS_TOKEN="..." GA4_REFRESH_TOKEN="..." GA4_CLIENT_ID="..." GA4_CLIENT_SECRET="..." node dist/index.js

# With Service Account
GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json" node dist/index.js
```

## Available Tools

### Admin API Tools

| Tool | Description |
|------|-------------|
| `ga4_account_summaries` | List all GA4 accounts and properties the user has access to |
| `ga4_property_details` | Get detailed information about a specific property |
| `ga4_google_ads_links` | List Google Ads accounts linked to a property |
| `ga4_property_annotations` | List annotations for a property (limited support) |

### Data API Tools

| Tool | Description |
|------|-------------|
| `ga4_run_report` | Run a standard GA4 report with dimensions, metrics, and date ranges |
| `ga4_run_realtime_report` | Run a realtime report for the last 30 minutes |
| `ga4_custom_dimensions_metrics` | Get custom dimensions and metrics defined for a property |

### GTM Validation Tool

| Tool | Description |
|------|-------------|
| `ga4_validate_gtm_params` | Validate GTM event parameters against GA4 custom dimensions and data collection |

## Example Usage

### Get Account Summaries
```json
{
  "tool": "ga4_account_summaries"
}
```

### Run a Report
```json
{
  "tool": "ga4_run_report",
  "arguments": {
    "propertyId": "123456789",
    "dateRanges": [
      {"startDate": "30daysAgo", "endDate": "yesterday"}
    ],
    "dimensions": ["country", "deviceCategory"],
    "metrics": ["activeUsers", "sessions"]
  }
}
```

### Run Realtime Report
```json
{
  "tool": "ga4_run_realtime_report",
  "arguments": {
    "propertyId": "123456789",
    "dimensions": ["country"],
    "metrics": ["activeUsers"]
  }
}
```

### Validate GTM Parameters
```json
{
  "tool": "ga4_validate_gtm_params",
  "arguments": {
    "propertyId": "123456789",
    "gtmEvents": [
      {
        "eventName": "purchase",
        "parameters": ["transaction_id", "value", "currency"]
      }
    ],
    "startDate": "7daysAgo",
    "endDate": "yesterday"
  }
}
```

Or with GTM Export JSON:
```json
{
  "tool": "ga4_validate_gtm_params",
  "arguments": {
    "propertyId": "123456789",
    "gtmExportJson": { "...GTM container export data..." }
  }
}
```

## GTM Integration (Claude Agent Orchestration)

This server works with the GTM MCP Server to provide end-to-end validation of GTM event parameters in GA4.

### Architecture

```
┌─────────────────────────────────────────────────────────────────────┐
│                        Claude Agent                                 │
│                    (Orchestrator Role)                              │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ① GTM MCP Server                  ② GA4 MCP Server                │
│  (gtmAgent/mcp-server)             (ga4-mcp-server)                 │
│                                                                     │
│  gtm_export_full()                 ga4_validate_gtm_params()        │
│  gtm_tag().list()                  ga4_custom_dimensions_metrics()  │
│       │                            ga4_run_report()                 │
│       │                                   ▲                         │
│       └───────────────────────────────────┘                         │
│                Agent relays data                                    │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
```

### Workflow

1. **Extract from GTM**: `gtm_export_full()` → Get GA4 Event tags and parameters
2. **Validate in GA4**: `ga4_validate_gtm_params()` → Check registration and collection
3. **Get recommendations**: Parameters not registered or not collecting data

### Claude Desktop Configuration (Both Servers)

```json
{
  "mcpServers": {
    "gtm": {
      "command": "node",
      "args": ["/path/to/gtmAgent/mcp-server/dist/index.js"],
      "env": {}
    },
    "ga4": {
      "command": "node",
      "args": ["/path/to/ga4-mcp-server/dist/index.js"],
      "env": {
        "GA4_ACCESS_TOKEN": "your-access-token",
        "GA4_REFRESH_TOKEN": "your-refresh-token",
        "GA4_CLIENT_ID": "your-client-id",
        "GA4_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}
```

### API Call Efficiency

| Scenario | Traditional | Optimized | Reduction |
|----------|-------------|-----------|-----------|
| 5 events × 21 params | 105 calls | 22 calls | 79% |
| 14 events × 32 params | 448 calls | 33 calls | 93% |

The validation tool queries metadata once, then makes one API call per unique parameter instead of per event-parameter combination.

## API Documentation References

- [GA4 Admin API](https://developers.google.com/analytics/devguides/config/admin/v1)
- [GA4 Data API](https://developers.google.com/analytics/devguides/reporting/data/v1)
- [Standard Dimensions](https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema#dimensions)
- [Standard Metrics](https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema#metrics)
- [Realtime Dimensions](https://developers.google.com/analytics/devguides/reporting/data/v1/realtime-api-schema#dimensions)
- [Realtime Metrics](https://developers.google.com/analytics/devguides/reporting/data/v1/realtime-api-schema#metrics)

## Required Google API Scopes

The server uses the following scope:
- `https://www.googleapis.com/auth/analytics.readonly`

## License

MIT