@byterover/umami-mcp

A minimal, read-only Model Context Protocol server for Umami 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 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

npx @byterover/umami-mcp

Configure

Pick one mode via environment variables.

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

UMAMI_API_KEY=your_api_key

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

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):

{
  "mcpServers": {
    "umami": {
      "command": "npx",
      "args": ["-y", "@byterover/[email protected]"],
      "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

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

License

Elastic License 2.0 — © byterover.