Umami MCP server

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:

• sendevent, sendidentify, send_performance
• batch_events (raw JSON array, up to 500 items)
• heartbeat, getshare, getrecorder_config

If self-hosted login reports that two-factor authentication is required, call completetwofactor_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

Shortened. The full README is on GitHub.