# Google Analytics MCP Server

A FastMCP server that provides AI agents with comprehensive access to Google Analytics 4 data via the Model Context Protocol (MCP).

## Features

- **18 MCP tools** covering all aspects of Google Analytics 4
- **HTTP streaming transport** for scalable deployments
- **Service account authentication** for automated server-to-server access
- **Dynamic property discovery** across all accessible GA4 accounts
- **Historical reports** with flexible dimensions, metrics, and date ranges
- **Realtime data** for current user activity
- **Custom dimensions/metrics** support

## Installation

```bash
# Clone the repository
git clone <repo-url>
cd google-analytics-mcp

# Install dependencies with uv
uv sync
```

## Configuration

### Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `GOOGLE_APPLICATION_CREDENTIALS` | Yes* | - | Path to service account JSON file |
| `MCP_HOST` | No | `0.0.0.0` | Host to bind the server |
| `MCP_PORT` | No | `8000` | Port for the server |

*Can also use Application Default Credentials (ADC) via `gcloud auth application-default login`

### Google Cloud Setup

#### Step 1: Create a Google Cloud Project (if you don't have one)

1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
2. Click the project dropdown at the top of the page
3. Click **New Project**
4. Enter a project name (e.g., "GA MCP Server")
5. Click **Create**
6. Wait for the project to be created, then select it from the project dropdown

#### Step 2: Enable Required APIs

1. In the Google Cloud Console, go to **APIs & Services** > **Library**
2. Search for and enable these APIs:
   - **Google Analytics Data API** - for running reports
   - **Google Analytics Admin API** - for listing properties

   For each API:
   - Click on the API name
   - Click **Enable**

#### Step 3: Create a Service Account

1. In the Google Cloud Console, go to **IAM & Admin** > **Service Accounts**
2. Click **+ Create Service Account** at the top
3. Fill in the details:
   - **Service account name**: `ga-mcp-server`
   - **Service account ID**: (auto-filled based on name)
   - **Description**: "Service account for Google Analytics MCP Server"
4. Click **Create and Continue**
5. Skip the optional "Grant this service account access" step (click **Continue**)
6. Skip the optional "Grant users access" step (click **Done**)

#### Step 4: Create and Download the Credentials JSON Key

1. In the Service Accounts list, find your newly created service account
2. Click on the service account email to open its details
3. Go to the **Keys** tab
4. Click **Add Key** > **Create new key**
5. Select **JSON** as the key type
6. Click **Create**
7. The JSON key file will automatically download to your computer
8. **Important**: Move this file to a secure location and note the path
   ```bash
   # Example: move to your project directory
   mv ~/Downloads/your-project-xxxxx.json ./credentials.json
   ```

> **Security Warning**: This JSON file contains sensitive credentials. Never commit it to version control or share it publicly.

#### Step 5: Grant the Service Account Access to Google Analytics

The service account needs explicit access to your GA4 properties. Without this step, `list_properties` will return an empty list.

**Find your service account email:**
1. Go to [Google Cloud Console > IAM & Admin > Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts)
2. Find your service account and copy the email address
   - It looks like: `ga-mcp-server@your-project.iam.gserviceaccount.com`

**Grant access in Google Analytics:**

1. Go to [Google Analytics](https://analytics.google.com/)
2. Click the **Admin** gear icon (bottom left corner)
3. Choose where to grant access:

   **Option A: Account Level (recommended)** - Grants access to ALL properties under the account:
   - In the **Account** column, click **Account Access Management**

   **Option B: Property Level** - Grants access to a specific property only:
   - First select the property from the Property dropdown
   - In the **Property** column, click **Property Access Management**

4. Click the **+** button in the top right
5. Select **Add users**
6. In the "Email addresses" field, paste your service account email
7. Under "Direct roles and data restrictions":
   - Select **Viewer** (sufficient for reading all analytics data)
   - Leave data restrictions unchecked for full access
8. Click **Add**

**Verify access was granted:**
- The service account email should now appear in the users list
- You can test by calling `list_properties` - it should return your properties

> **Note:** It may take a few minutes for permissions to propagate. If `list_properties` still returns empty, wait 2-3 minutes and try again.

#### Step 6: Set the Environment Variable

```bash
# Option 1: Set for current terminal session
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json

# Option 2: Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
echo 'export GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json' >> ~/.bashrc
source ~/.bashrc

# Option 3: Create a .env file in the project directory
cp .env.example .env
# Then edit .env and set the path to your credentials file
```

#### Alternative: Using Application Default Credentials (ADC)

If you prefer not to use a service account, you can authenticate with your personal Google account:

```bash
gcloud auth application-default login \
  --scopes=https://www.googleapis.com/auth/analytics.readonly
```

This is useful for local development but not recommended for production deployments.

## Usage

### Running the Server

```bash
# Using uv
uv run python main.py

# Or directly
python main.py
```

The server starts on `http://0.0.0.0:8000` by default.

### MCP Client Configuration

Add to your MCP client configuration (e.g., Claude Desktop):

```json
{
  "mcpServers": {
    "google-analytics": {
      "url": "http://localhost:8000/mcp"
    }
  }
}
```

## Available Tools

### Discovery Tools

| Tool | Description |
|------|-------------|
| `list_properties` | List all accessible GA4 properties |
| `get_property_details` | Get property info (timezone, currency, etc.) |
| `get_available_metrics` | Get all dimensions/metrics for a property |

### Historical Report Tools

| Tool | Description |
|------|-------------|
| `run_custom_report` | Flexible report with any dimensions/metrics |
| `get_traffic_summary` | Daily users, sessions, pageviews, bounce rate |
| `get_acquisition_report` | Traffic sources breakdown |
| `get_page_performance` | Top pages by pageviews |
| `get_geographic_report` | Users by country/city |
| `get_device_report` | Desktop/mobile/tablet breakdown |
| `get_events_report` | Top events by count |
| `compare_periods` | Period-over-period comparison |

### Realtime Tools

| Tool | Description |
|------|-------------|
| `get_realtime_overview` | Current active users overview |
| `get_realtime_pages` | Currently active pages |
| `get_realtime_traffic_sources` | Current traffic sources |
| `get_realtime_events` | Events occurring now |
| `run_custom_realtime_report` | Custom realtime query |

### Admin Tools

| Tool | Description |
|------|-------------|
| `list_custom_dimensions` | Property's custom dimensions |
| `list_custom_metrics` | Property's custom metrics |

## Example Usage (AI Agent)

```
1. list_properties()
   -> Discover all accessible GA4 properties

2. get_property_details("123456789")
   -> Get timezone, currency, and other property metadata

3. get_traffic_summary("123456789", "7daysAgo", "today")
   -> Get daily traffic metrics for the last week

4. get_acquisition_report("123456789", "yesterday", "yesterday")
   -> See where yesterday's traffic came from

5. compare_periods("123456789", "7daysAgo", "today", "14daysAgo", "8daysAgo")
   -> Compare this week to last week

6. get_realtime_overview("123456789")
   -> See who's on the site right now
```

## Project Structure

```
google-analytics-mcp/
├── pyproject.toml          # Dependencies and build config
├── main.py                 # Server entry point
├── src/
│   ├── __init__.py
│   ├── config.py           # Environment variable settings
│   ├── clients/
│   │   ├── __init__.py
│   │   ├── admin_client.py # GA Admin API wrapper
│   │   └── data_client.py  # GA Data API wrapper
│   └── tools/
│       ├── __init__.py
│       ├── discovery.py    # Property discovery tools
│       ├── reports.py      # Historical report tools
│       ├── realtime.py     # Realtime data tools
│       └── admin.py        # Custom dimensions/metrics
```

## License

MIT