English | 한국어

umami-mcp

Model Context Protocol server for the current Umami Analytics v3.3 API.
It supports self-hosted username/password authentication and Umami Cloud API
keys, and exposes analytics, collection, administration, and newer 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 and the public v3.3.1 server contracts.

Requirements

• Node.js 18 or newer
• Umami v3.3-compatible self-hosted instance, or an Umami Cloud API key

Installation

npm install -g @mikusnuz/umami-mcp

Or run it directly:

npx -y @mikusnuz/umami-mcp

Configuration

Self-hosted

{
  "mcpServers": {
    "umami": {
      "command": "npx",
      "args": ["-y", "@mikusnuz/umami-mcp"],
      "env": {
        "UMAMI_URL": "https://analytics.example.com",
        "UMAMI_USERNAME": "admin",
        "UMAMI_PASSWORD": "your-password"
      }
    }
  }
}

UMAMI_URL is the instance origin. A trailing /api is accepted, but is not
required.

Umami Cloud

{
  "mcpServers": {
    "umami": {
      "command": "npx",
      "args": ["-y", "@mikusnuz/umami-mcp"],
      "env": {
        "UMAMI_API_KEY": "your-cloud-api-key"
      }
    }
  }
}

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.

Environment variables

For Cloud, the collector defaults to https://cloud.umami.is. For self-hosted
Umami it defaults to UMAMI_URL.

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; Cloud uses the API key
as the bearer credential.

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

Use MCP tools/list for the complete, machine-readable list and schemas.

Important v3 contract details

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

Development

npm install
npm test

npm test builds the TypeScript server, checks Cloud/self-hosted URL and auth
behavior, verifies raw public batch requests and the 2FA login flow, and
validates key MCP schemas.

Official references

• Umami API overview
• Authentication
• Cloud API keys
• Sending statistics
• Website statistics
• Reports
• Cloud/API changelog
• Umami v3.3.1 server source

License

MIT