{"_id":"@byterover/umami-mcp","_rev":"2-8872a97dc3c39862e90ef9fd62ed7dca","name":"@byterover/umami-mcp","dist-tags":{"latest":"0.2.2"},"versions":{"0.2.2":{"name":"@byterover/umami-mcp","version":"0.2.2","keywords":["umami","analytics","mcp","model-context-protocol","byterover","grove"],"license":"Elastic-2.0","_id":"@byterover/umami-mcp@0.2.2","maintainers":[{"name":"byteroverinc","email":"andy@byterover.dev"},{"name":"lincoln_byterover","email":"lincoln@byterover.dev"}],"bin":{"umami-mcp":"dist/index.js"},"dist":{"shasum":"7fcab1617ca4599a47a529e2e4f79c0fac4b2ae1","tarball":"https://registry.npmjs.org/@byterover/umami-mcp/-/umami-mcp-0.2.2.tgz","fileCount":15,"integrity":"sha512-eTGWDTP9PdSAvSGCb6bCyWE1ml5RIdxdcPeSrJJ1lqQniE4DMjAI5In91UNXbPtoVXiKvrc3LXWS50RGN8AE9Q==","signatures":[{"sig":"MEQCIEuxCuJ6erDen+uRkwaSaY3tI+NCpwRmDRw6RU4aserdAiAyADJKIKxewRNKG3RuVHIG1wvlFAHQgqIYryzzMZ6IiQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":63978},"type":"module","engines":{"node":">=20"},"exports":{".":"./dist/index.js"},"gitHead":"672528d0b1d6f2effbd546ed0e5221e385bd89d7","scripts":{"lint":"biome check .","test":"vitest run","build":"tsc -p tsconfig.build.json","start":"node dist/index.js","format":"biome format --write .","typecheck":"tsc -p tsconfig.build.json --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"lincoln_byterover","email":"lincoln@byterover.dev"},"_npmVersion":"10.9.8","description":"A minimal, read-only Model Context Protocol server for Umami analytics (Cloud or self-hosted).","directories":{},"_nodeVersion":"22.23.1","dependencies":{"@modelcontextprotocol/sdk":"1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"2.1.8","typescript":"5.7.3","@types/node":"22.10.5","@biomejs/biome":"2.3.5"},"_npmOperationalInternal":{"tmp":"tmp/umami-mcp_0.2.2_1783222511018_0.7862154642392654","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-07-05T03:35:10.850Z","modified":"2026-07-05T03:44:46.826Z","0.2.2":"2026-07-05T03:35:11.147Z"},"license":"Elastic-2.0","keywords":["umami","analytics","mcp","model-context-protocol","byterover","grove"],"description":"A minimal, read-only Model Context Protocol server for Umami analytics (Cloud or self-hosted).","maintainers":[{"email":"bao@byterover.dev","name":"baobyterover"},{"email":"andy@byterover.dev","name":"byteroverinc"},{"email":"lincoln@byterover.dev","name":"lincoln_byterover"}],"readme":"# @byterover/umami-mcp\n\nA minimal, **read-only** [Model Context Protocol](https://modelcontextprotocol.io)\nserver for [Umami](https://umami.is) analytics — Cloud or self-hosted.\n\nIt exposes a small set of read tools (list sites, stats, time series, top\nmetrics, live visitors) over stdio, so an MCP client such as\n[Grove](https://github.com/campfirein/grove) can let an agent answer questions\nabout your web analytics. It issues **no writes** — there are no create/update/\ndelete tools, by design.\n\n## Why this exists\n\nCommunity Umami MCP servers exist but have little usage and aren't reviewed by\nanyone we trust with an analytics credential. This is byterover's first-party,\nsource-available wrapper: small enough to read end-to-end, read-only, and\npublished with provenance. We dogfood it on our own landing-page analytics.\n\n## Install\n\n```sh\nnpx @byterover/umami-mcp\n```\n\n## Configure\n\nPick **one** mode via environment variables.\n\n**Umami Cloud** — create a read-only API key at\n[cloud.umami.is](https://cloud.umami.is) (Settings → API keys):\n\n```sh\nUMAMI_API_KEY=your_api_key\n```\n\n**Self-hosted** — point at your instance and provide a login:\n\n```sh\nUMAMI_API_URL=https://umami.example.com\nUMAMI_USERNAME=your_username\nUMAMI_PASSWORD=your_password\n```\n\nAdvanced: `UMAMI_API_URL` overrides the base host (Cloud default\n`https://api.umami.is`) and `UMAMI_API_PATH` overrides the path prefix (Cloud\n`/v1`, self-hosted `/api`).\n\n## Use with Grove\n\nAdd it to your `mcp.json` as a stdio server (pin the version; keep the key in\n`.env` via a `${VAR}` ref):\n\n```json\n{\n  \"mcpServers\": {\n    \"umami\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@byterover/umami-mcp@0.1.0\"],\n      \"env\": { \"UMAMI_API_KEY\": \"${UMAMI_API_KEY}\" }\n    }\n  }\n}\n```\n\nTools surface in Grove as `umami__list_websites`, `umami__website_stats`, etc.\n\n## Tools\n\nThirteen read tools covering essentially all of Umami's analytics reads —\nconsolidated (one `metrics` tool spans ~10 dimensions; `explore_event_data`\nfolds five endpoints behind a `mode`), never mirroring the REST API 1:1.\n\n**Discovery**\n| Tool | What it returns |\n| --- | --- |\n| `list_websites` | Websites (id, name, domain) these credentials can see. Start here. |\n| `data_range` | Earliest/latest timestamps with data — call before querying ranges. |\n\n**Traffic & trends**\n| Tool | What it returns |\n| --- | --- |\n| `website_stats` | Pageviews, visitors, visits, bounces, total time (with prior period). |\n| `pageviews_series` | Pageviews/sessions time series, bucketed by hour/day/month/year. |\n| `realtime` | Live activity in the last ~30 min (active visitors, recent views/events). |\n\n**Breakdowns & events**\n| Tool | What it returns |\n| --- | --- |\n| `metrics` | Top values for one dimension (url, referrer, browser, country, event, …); `expanded=true` adds engagement. |\n| `events_series` | Custom-event time series over a range. |\n| `explore_event_data` | Drill into event properties/values (`mode`: events / properties / fields / stats / values). |\n\n**Sessions & journeys**\n| Tool | What it returns |\n| --- | --- |\n| `list_sessions` | Individual visitor sessions (paginated, searchable). |\n| `session_detail` | One session's summary + activity log + custom properties. |\n\n**Analyses** (compute-reads, POST — still read-only)\n| Tool | What it returns |\n| --- | --- |\n| `funnel_report` | Conversion funnel across ordered steps (paths/events). |\n| `retention_report` | Return-visitor retention over the range (needs a timezone). |\n| `journey_report` | Common navigation paths between a start and (optional) end step. |\n\nRange tools accept ISO `startAt`/`endAt`; report tools accept ISO\n`startDate`/`endDate` (e.g. `2026-07-01`). Omit them for the last 7 days.\n\n## Develop\n\n```sh\npnpm install\npnpm build       # tsc → dist/\npnpm typecheck\npnpm test        # keyless, network-free\npnpm lint\n```\n\n## License\n\n[Elastic License 2.0](./LICENSE) — © byterover.\n","readmeFilename":"README.md"}