# google-analytics-mcp

A small, stateless MCP server for Google Analytics 4 (Data API + Admin API), served over Streamable HTTP.

It never stores credentials. Every request must carry `Authorization: Bearer <Google access token>`, and the server uses that token for that one request. An auth proxy such as [Nango](https://nango.dev) keeps the Google login, refreshes it, and adds the header. Because the token decides which account is used, one container serves any number of Google accounts.

```
MCP client ──► auth proxy (Nango: stores + refreshes the Google login)
                  │  Authorization: Bearer ya29…
                  ▼
          google-analytics-mcp  ──►  GA4 Data API / Admin API
```

## Tools (all read-only)

| Tool | What it does |
|---|---|
| `list_properties` | GA accounts and GA4 properties the account can access, with numeric property ids |
| `get_property` | Property settings (time zone, currency, industry) |
| `run_report` | Any GA4 report: metrics × dimensions, date range, string filters, ordering, paging, totals |
| `run_realtime_report` | Users active in the last 30 minutes, by page, country, device, event |
| `get_overview` | One call: totals, top pages, top channels, top sources for a date range |
| `get_metadata` | Available dimensions and metrics, including custom ones |

Dates accept `YYYY-MM-DD`, `today`, `yesterday` or `NdaysAgo`.

## Google setup

- Scope on the token: `https://www.googleapis.com/auth/analytics.readonly`.
- In the Google Cloud project that owns the OAuth client, enable **Google Analytics Data API** and **Google Analytics Admin API**.

## Configuration

| Env var | Default | Purpose |
|---|---|---|
| `PORT` | `8000` | Listen port |
| `HOST` | `0.0.0.0` | Listen address |
| `MCP_PATH` | `/mcp` | MCP endpoint path |
| `GA_TIMEOUT_MS` | `30000` | Timeout for each Google API call |

`GET /health` returns `{"ok":true}`. The server is stateless: only `POST /mcp` is served (GET and DELETE return 405), and a request without a bearer token gets 401.

## Run

```bash
npm ci && npm run build
PORT=8000 node dist/index.js
```

or with Docker:

```bash
docker build -t google-analytics-mcp-http .
docker run --rm -p 8000:8000 google-analytics-mcp-http
```

Keep it on a private network behind the auth proxy.

## License

MIT