mikusnuz/umami-mcp

umami-mcp
Model Context Protocol server for the **Umami Analytics v3 API**.
It supports self-hosted username/password or API-key authentication and Umami
Cloud API keys, and exposes analytics, collection, administration, and v3 feature
families such as boards, links, pixels, segments, session replay, shares,
exports, performance, and revenue.
This version intentionally does not claim every private Umami route. Its tools
track the documented API, including Umami 3.4 API-key authentication. Report
tools use the legacy report contracts that Umami 3.4 continues to support.
Requirements
- Node.js 18 or newer
- Umami v3.3-compatible self-hosted instance (3.4+ for API keys), or Umami Cloud
Installation
Or run it directly:
Configuration
Self-hosted
UMAMI_URL is the instance origin. A trailing /api is accepted, but is not
required.
On Umami 3.4+, create an API key under Settings → API keys and replace
UMAMI_USERNAME and UMAMI_PASSWORD with UMAMI_API_KEY. Set
UMAMI_MODE to self-hosted to select the deployment mode explicitly.
Umami Cloud
Cloud management calls default to https://api.umami.is/v1; tool paths are
translated from self-hosted /api/... paths to Cloud /v1/... paths. Set
UMAMI_URL to https://api.umami.is/v1/us or
https://api.umami.is/v1/eu when an explicit Cloud region is required.
For a Cloud API proxy on another hostname, also set UMAMI_MODE to cloud.
Environment variables
| Variable | When required | Description |
|---|---|---|
| UMAMI_MODE | Optional | self-hosted or cloud; auto-detected when omitted |
| UMAMI_URL | Self-hosted | Instance origin; optional for Cloud |
| UMAMI_USERNAME | Without a self-hosted API key | Login username |
| UMAMI_PASSWORD | Without a self-hosted API key | Login password |
| UMAMI_API_KEY | Cloud; optional for self-hosted 3.4+ | Bearer API key |
| UMAMI_COLLECTOR_URL | Optional | Separate host for public collection/share/heartbeat/recorder routes |
For Cloud, the collector defaults to https://cloud.umami.is. For self-hosted
Umami it defaults to UMAMI_URL.
An API key without UMAMI_URL, or a URL on api.umami.is, selects Cloud.
Any other configured URL selects self-hosted mode, even when using an API key.
Authentication and public routes
Management and analytics tools send a bearer token. The client logs in to a
self-hosted instance lazily and caches the returned JWT when using a password.
API keys are sent directly as the bearer credential on both deployment types.
The public collection routes do not require credentials:
- send_event, send_identify, send_performance
- batch_events (raw JSON array, up to 500 items)
- heartbeat, get_share, get_recorder_config
If self-hosted login reports that two-factor authentication is required, call
complete_two_factor_login with a current TOTP or backup code, then retry the
original tool. Setup and policy tools are also exposed for self-hosted Umami.
Umami Cloud does not expose /me/password, /users, or /users/* through an
API key. Those tools are for self-hosted instances.
Tool groups
| Area | Representative tools |
|---|---|
| Websites | list_websites, CRUD, reset, transfer to user/team, replay configuration |