@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.

Related MCP server: Umami MCP Server

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/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

Traffic & trends

Breakdowns & events

Sessions & journeys

Analyses (compute-reads, POST — still read-only)

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.