{
  "markdown": "**English** | [한국어](README.ko.md)\n\n# umami-mcp\n\nModel Context Protocol server for the current **Umami Analytics v3.3 API**.\nIt supports self-hosted username/password authentication and Umami Cloud API\nkeys, and exposes analytics, collection, administration, and newer v3 feature\nfamilies such as boards, links, pixels, segments, session replay, shares,\nexports, performance, and revenue.\n\nThis version intentionally does not claim every private Umami route. Its tools\ntrack the documented API and the public v3.3.1 server contracts.\n\n## Requirements\n\n- Node.js 18 or newer\n- Umami v3.3-compatible self-hosted instance, or an Umami Cloud API key\n\n## Installation\n\n```bash\nnpm install -g @mikusnuz/umami-mcp\n```\n\nOr run it directly:\n\n```bash\nnpx -y @mikusnuz/umami-mcp\n```\n\n## Configuration\n\n### Self-hosted\n\n```json\n{\n  \"mcpServers\": {\n    \"umami\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@mikusnuz/umami-mcp\"],\n      \"env\": {\n        \"UMAMI_URL\": \"https://analytics.example.com\",\n        \"UMAMI_USERNAME\": \"admin\",\n        \"UMAMI_PASSWORD\": \"your-password\"\n      }\n    }\n  }\n}\n```\n\n`UMAMI_URL` is the instance origin. A trailing `/api` is accepted, but is not\nrequired.\n\n### Umami Cloud\n\n```json\n{\n  \"mcpServers\": {\n    \"umami\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@mikusnuz/umami-mcp\"],\n      \"env\": {\n        \"UMAMI_API_KEY\": \"your-cloud-api-key\"\n      }\n    }\n  }\n}\n```\n\nCloud management calls default to `https://api.umami.is/v1`; tool paths are\ntranslated from self-hosted `/api/...` paths to Cloud `/v1/...` paths. Set\n`UMAMI_URL` to `https://api.umami.is/v1/us` or\n`https://api.umami.is/v1/eu` when an explicit Cloud region is required.\n\n### Environment variables\n\n| Variable | When required | Description |\n|---|---|---|\n| `UMAMI_URL` | Self-hosted | Instance origin; optional for Cloud |\n| `UMAMI_USERNAME` | Self-hosted | Login username |\n| `UMAMI_PASSWORD` | Self-hosted | Login password |\n| `UMAMI_API_KEY` | Cloud | Bearer API key |\n| `UMAMI_COLLECTOR_URL` | Optional | Separate host for public collection/share/heartbeat/recorder routes |\n\nFor Cloud, the collector defaults to `https://cloud.umami.is`. For self-hosted\nUmami it defaults to `UMAMI_URL`.\n\n## Authentication and public routes\n\nManagement and analytics tools send a bearer token. The client logs in to a\nself-hosted instance lazily and caches the returned JWT; Cloud uses the API key\nas the bearer credential.\n\nThe public collection routes do not require credentials:\n\n- `send_event`, `send_identify`, `send_performance`\n- `batch_events` (raw JSON array, up to 500 items)\n- `heartbeat`, `get_share`, `get_recorder_config`\n\nIf self-hosted login reports that two-factor authentication is required, call\n`complete_two_factor_login` with a current TOTP or backup code, then retry the\noriginal tool. Setup and policy tools are also exposed for self-hosted Umami.\n\nUmami Cloud does not expose `/me/password`, `/users`, or `/users/*` through an\nAPI key. Those tools are for self-hosted instances.\n\n## Tool groups\n\n| Area | Representative tools |\n|---|---|\n| Websites | `list_websites`, CRUD, reset, transfer to user/team, replay configuration |\n| Analytics | `get_stats`, `get_pageviews`, `get_metrics`, `get_events`, `get_sessions`, event series |\n| Event/session data | event values, fields, properties, values, session activity |\n| Collection | event/pageview, identify, performance, raw batch, link/pixel events |\n| Reports | saved-report CRUD and `run_report` for attribution, breakdown, funnel, goal, heatmap, journey, performance, retention, revenue, and UTM |\n| Boards | list, CRUD, clone, and team boards |\n| Links and pixels | list, CRUD, charts, and collection events |\n| Segments | segment/cohort list and CRUD |\n| Replay | recorder config, replay list/detail, saved replays, session replays |\n| Shares and export | public share resolution, managed website shares, update/delete, CSV ZIP export |\n| Revenue | stats, chart, metrics, and revenue sessions |\n| Users and teams | current admin-user and team membership/transfer routes |\n| 2FA | login completion, enrollment, disable, and admin enforcement policies |\n| Realtime | `get_realtime` |\n\nUse MCP `tools/list` for the complete, machine-readable list and schemas.\n\n## Important v3 contract details\n\n- A pageview is sent as `{ \"type\": \"event\" }` with no event `name`; the old\n  `pageview` type is no longer valid.\n- `/api/batch` receives the event objects as a raw array, not\n  `{ \"events\": [...] }`. The tool returns Umami's `processed`, `errors`, and\n  per-item `details` fields and marks partial failures as an MCP error result.\n- Collector calls set a stable non-bot `User-Agent` header as required by\n  Umami; `send_event` and batch items may also supply the visitor's\n  `userAgent` and trusted server-side `ip` in the payload.\n- Analytics URL filters and page metrics use `path`; the old `url` metric was\n  removed. Host aggregation uses `hostname`.\n- Supported time units are `minute`, `hour`, `day`, `month`, and `year`.\n- `get_event_series` and `get_sessions_weekly` require an IANA timezone.\n- `list_reports` requires `websiteId`; report execution sends\n  `{ websiteId, type, filters, parameters }`.\n- Team website membership is changed through `transfer_website`; the removed\n  team-website POST/DELETE routes are not exposed.\n\n## Development\n\n```bash\nnpm install\nnpm test\n```\n\n`npm test` builds the TypeScript server, checks Cloud/self-hosted URL and auth\nbehavior, verifies raw public batch requests and the 2FA login flow, and\nvalidates key MCP schemas.\n\n## Official references\n\n- [Umami API overview](https://docs.umami.is/docs/api)\n- [Authentication](https://docs.umami.is/docs/api/authentication)\n- [Cloud API keys](https://docs.umami.is/docs/cloud/api-key)\n- [Sending statistics](https://docs.umami.is/docs/api/sending-stats)\n- [Website statistics](https://docs.umami.is/docs/api/website-stats)\n- [Reports](https://docs.umami.is/docs/api/reports)\n- [Cloud/API changelog](https://docs.umami.is/docs/cloud/changelog)\n- [Umami v3.3.1 server source](https://github.com/umami-software/umami/tree/v3.3.1)\n\n## License\n\nMIT\n",
  "bytes": 6088,
  "sha": "cb304fd0445e470966e39e7dfcf43cab6a859032fec34bc6148e7a39a0466b6d",
  "repo_slug": "mikusnuz/umami-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mikusnuz_umami_cf8937aa/readme"
}