# @byterover/umami-mcp

A minimal, **read-only** [Model Context Protocol](https://modelcontextprotocol.io)
server for [Umami](https://umami.is) analytics — Cloud or self-hosted.

It exposes a small set of read tools (list sites, stats, time series, top
metrics, live visitors) over stdio, so an MCP client such as
[Grove](https://github.com/campfirein/grove) can let an agent answer questions
about your web analytics. It issues **no writes** — there are no create/update/
delete tools, by design.

## Why this exists

Community Umami MCP servers exist but have little usage and aren't reviewed by
anyone we trust with an analytics credential. This is byterover's first-party,
source-available wrapper: small enough to read end-to-end, read-only, and
published with provenance. We dogfood it on our own landing-page analytics.

## Install

```sh
npx @byterover/umami-mcp
```

## Configure

Pick **one** mode via environment variables.

**Umami Cloud** — create a read-only API key at
[cloud.umami.is](https://cloud.umami.is) (Settings → API keys):

```sh
UMAMI_API_KEY=your_api_key
```

**Self-hosted** — point at your instance and provide a login:

```sh
UMAMI_API_URL=https://umami.example.com
UMAMI_USERNAME=your_username
UMAMI_PASSWORD=your_password
```

Advanced: `UMAMI_API_URL` overrides the base host (Cloud default
`https://api.umami.is`) and `UMAMI_API_PATH` overrides the path prefix (Cloud
`/v1`, self-hosted `/api`).

## Use with Grove

Add it to your `mcp.json` as a stdio server (pin the version; keep the key in
`.env` via a `${VAR}` ref):

```json
{
  "mcpServers": {
    "umami": {
      "command": "npx",
      "args": ["-y", "@byterover/umami-mcp@0.1.0"],
      "env": { "UMAMI_API_KEY": "${UMAMI_API_KEY}" }
    }
  }
}
```

Tools surface in Grove as `umami__list_websites`, `umami__website_stats`, etc.

## Tools

Thirteen read tools covering essentially all of Umami's analytics reads —
consolidated (one `metrics` tool spans ~10 dimensions; `explore_event_data`
folds five endpoints behind a `mode`), never mirroring the REST API 1:1.

**Discovery**
| Tool | What it returns |
| --- | --- |
| `list_websites` | Websites (id, name, domain) these credentials can see. Start here. |
| `data_range` | Earliest/latest timestamps with data — call before querying ranges. |

**Traffic & trends**
| Tool | What it returns |
| --- | --- |
| `website_stats` | Pageviews, visitors, visits, bounces, total time (with prior period). |
| `pageviews_series` | Pageviews/sessions time series, bucketed by hour/day/month/year. |
| `realtime` | Live activity in the last ~30 min (active visitors, recent views/events). |

**Breakdowns & events**
| Tool | What it returns |
| --- | --- |
| `metrics` | Top values for one dimension (url, referrer, browser, country, event, …); `expanded=true` adds engagement. |
| `events_series` | Custom-event time series over a range. |
| `explore_event_data` | Drill into event properties/values (`mode`: events / properties / fields / stats / values). |

**Sessions & journeys**
| Tool | What it returns |
| --- | --- |
| `list_sessions` | Individual visitor sessions (paginated, searchable). |
| `session_detail` | One session's summary + activity log + custom properties. |

**Analyses** (compute-reads, POST — still read-only)
| Tool | What it returns |
| --- | --- |
| `funnel_report` | Conversion funnel across ordered steps (paths/events). |
| `retention_report` | Return-visitor retention over the range (needs a timezone). |
| `journey_report` | Common navigation paths between a start and (optional) end step. |

Range tools accept ISO `startAt`/`endAt`; report tools accept ISO
`startDate`/`endDate` (e.g. `2026-07-01`). Omit them for the last 7 days.

## Develop

```sh
pnpm install
pnpm build       # tsc → dist/
pnpm typecheck
pnpm test        # keyless, network-free
pnpm lint
```

## License

[Elastic License 2.0](./LICENSE) — © byterover.