umami-mcp

umami-mcp is a Model Context Protocol (MCP) server for connecting to the Umami Analytics API. It is built on the Umami Analytics v3 API and supports self-hosted instances (username/password or API key authentication) as well as Umami Cloud (API key authentication). The server provides access to analytics, data collection, administration, and v3 new features (such as dashboards, links, pixels, segments, session replay, sharing, export, performance, and revenue).

Main capabilities:

• Provides 66 tools, 2 resources, and 2 prompts, covering Umami's documented API routes.
• Supports self-hosted Umami v3.3-compatible instances (API keys require 3.4+) or Umami Cloud.
• Authentication methods: self-hosted can use username/password (lazy login with cached JWT) or API key; Cloud uses API key.
• Public collection routes require no credentials, including send_event, send_identify, send_performance, batch_events (raw JSON array, up to 500 items), heartbeat, get_share, get_recorder_config.
• Supports two-factor authentication: if self-hosted login requires 2FA, you can call complete_two_factor_login and provide a TOTP or backup code.
• Management tools (such as /me/password, /users, etc.) apply only to self-hosted instances; Cloud does not expose these routes via API key.

Usage:

• Requires Node.js 18 or higher.
• Configure via environment variables: UMAMI_URL is the instance origin (a trailing /api is accepted but not required); UMAMI_USERNAME and UMAMI_PASSWORD are used for self-hosted password authentication; UMAMI_API_KEY is used for API key authentication (can be created in settings in Umami 3.4+); UMAMI_MODE can be explicitly set to self-hosted or cloud.
• Cloud management calls default to using https://api.umami.is/v1，工具路径会从自托管的 /api/... converted to Cloud's /v1/.... To specify a Cloud region, you can set UMAMI_URL to https://api.umami.is/v1/us or https://api.umami.is/v1/eu。
• For Cloud, the collector defaults to using https://cloud.umami.is；自托管则默认使用 UMAMI_URL. Cloud is selected when only an API key is provided without UMAMI_URL, or when the URL is api.umami.is; other configured URLs select self-hosted mode.
• Management and analytics tools send a bearer token; public collection routes require no credentials.
• You can use MCP's tools/list to get the complete machine-readable tool list and schemas.

Important v3 contract details:

• Page views are sent as { "type": "event" } with no event name; the old pageview type is no longer valid.
• /api/batch accepts a raw array of event objects, not { "events": [...] }. The tool returns Umami's processed, errors, and per-item detail fields, and marks partial failures as MCP error results.
• Collector calls set a stable non-bot User-Agent header; send_event and batch items can also provide the visitor's userAgent and trusted server-side ip in the payload.
• Analytics URL filters and page metrics use path; the old url metric has been removed. Host aggregation uses hostname.
• Supported time units are minute, hour, day, month, year.
• get_event_series and get_sessions_weekly require an IANA time zone.
• list_reports requires websiteId; report execution sends { websiteId, type, filters, parameters }.
• Team website membership is changed via transfer_website; the removed team-website POST/DELETE routes are no longer exposed.

Use cases:

• Integrate Umami analytics data into AI assistants or automated workflows.
• Query website statistics, sessions, events, reports, etc. via the MCP protocol.
• Manage users, teams, and settings of self-hosted Umami instances.
• Leverage v3 features for advanced analytics, such as session replay, segments, and revenue tracking.

Limitations:

• Requires Node.js 18+ and a compatible Umami instance or Cloud account.
• This version intentionally does not claim to cover all private Umami routes, only tracking documented APIs.
• The reporting tool uses the legacy reporting contract still supported by Umami 3.4.
• Cloud does not expose administrative routes such as /me/password, /users, or /users/* via API keys.
• Some tools require specific parameters (such as timezone, websiteId).
• Specific charges, prices, and platform support details are not yet provided.