# GA4 Visualization MCP Server

An MCP server that enables interactive Google Analytics 4 visualizations inside Claude conversations.

## Features

- **OAuth Authentication**: Secure browser-based OAuth 2.0 PKCE flow
- **Ad-hoc Queries**: Run custom GA4 queries with dimension/metric selection
- **Interactive Charts**: Line, bar, pie charts and data tables using Chart.js
- **Dark Mode**: Automatic theme adaptation

## Setup

### Prerequisites

1. A Google Cloud project with the Google Analytics Data API enabled
2. OAuth 2.0 credentials configured for desktop application
3. A GA4 property ID

### Google Cloud Configuration

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Enable the **Google Analytics Data API**
3. Create OAuth 2.0 credentials:
   - Application type: **Desktop app**
   - Add `http://127.0.0.1:9876/callback` as an authorized redirect URI
4. Note your Client ID and Client Secret

### Installation

```bash
# Clone and install dependencies
cd mcp-ga4-viz
pnpm install

# Build both packages
pnpm build
```

### Configuration

Create a `.env` file in the project root:

```bash
GA4_PROPERTY_ID=123456789
GOOGLE_CLIENT_ID=xxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=xxx
```

### Claude Desktop Configuration

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "ga4-viz": {
      "command": "node",
      "args": ["/path/to/mcp-ga4-viz/packages/server/dist/index.js"],
      "env": {
        "GA4_PROPERTY_ID": "123456789",
        "GOOGLE_CLIENT_ID": "xxx.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "xxx"
      }
    }
  }
}
```

## Usage

### Authentication

First, authenticate with Google Analytics:

```
"Authenticate with Google Analytics"
```

This opens a browser window for OAuth consent. After authenticating, you can run queries.

### Running Queries

Example queries:

```
"Show me sessions by country for the last 7 days as a bar chart"

"Get pageviews and users by date for the last 30 days as a line chart"

"Show top 10 landing pages by sessions"
```

### Available Tools

| Tool | Description |
|------|-------------|
| `ga4_authenticate` | Manage OAuth authentication (login/status/logout) |
| `ga4_query` | Run ad-hoc GA4 queries with visualization |

### Common Dimensions

- `date`, `country`, `city`
- `deviceCategory`, `browser`, `operatingSystem`
- `sessionSource`, `sessionMedium`, `sessionCampaignName`
- `pagePath`, `pageTitle`, `landingPage`
- `eventName`

### Common Metrics

- `sessions`, `totalUsers`, `newUsers`, `activeUsers`
- `screenPageViews`, `eventCount`, `conversions`
- `engagedSessions`, `engagementRate`
- `averageSessionDuration`, `bounceRate`

## Development

```bash
# Run server in development mode
cd packages/server
pnpm dev

# Run UI in development mode
cd packages/ui-chart
pnpm dev
```

## Architecture

```
mcp-ga4-viz/
├── packages/
│   ├── server/           # MCP server + GA4 API + OAuth
│   │   ├── src/
│   │   │   ├── auth/     # OAuth PKCE flow, token management
│   │   │   ├── ga4/      # GA4 Data API client
│   │   │   └── tools/    # MCP tool implementations
│   │   └── dist/ui/      # Built UI assets
│   └── ui-chart/         # Preact + Chart.js visualization
└── pnpm-workspace.yaml
```

## License

MIT