Umami

MCP server for Umami Analytics v3 — analytics, boards, links, pixels, reports, replay, and more

LLM Mart 2 views 44 listing impressions

English | 한국어

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 20 or newer, matching the MCP SDK's installed runtime dependencies
  • Umami v3.3-compatible self-hosted instance (3.4+ for API keys, session-property segments and annotations), or Umami Cloud with the corresponding routes enabled

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.

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

{
  "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. 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

From the project's README.

Related servers

Read and write RAGE Package Format archives

23 views

See how ChatGPT, Claude, Gemini and Perplexity read any website. Scored out of 100.

19 views

MCP server for Geargrafx PC Engine / TurboGrafx-16 emulator

19 views

Read-only on-chain intel for AI agents on Base: balances, tokens, gas, tx status. No API keys.

15 views