ObsidianCorps Umami MCP

Ask questions about your self-hosted Umami analytics without sending the data to another analytics SaaS.

A secure, model-friendly Model Context Protocol server for Umami Cloud and self-hosted Umami Analytics. It targets Umami v3.3.1 and the 2026-07-28 MCP protocol, while retaining compatibility with 2025-era MCP clients.

Install

Requirements: Node.js 20 or newer and one configured authentication mode.

npx -y @obsidiancorps/umami-mcp

Try asking:

• “Compare website traffic with last month.”
• “Which sources generated the most conversions?”
• “Find pages with poor Web Vitals.”

Why this implementation

• Current Umami v3 coverage: revenue APIs, session replay, heatmaps, event/session property pivots and typed series, segments, cohorts, boards, links, pixels, Web Vitals reports, and the established analytics APIs.
• Compact model surface: 17 read tools organize the API around analytical workflows instead of advertising dozens of near-duplicate endpoint tools.
• Model-friendly inputs: website names/domains resolve automatically, one accessible website is selected automatically, and date ranges accept presets or exact ISO/epoch timestamps.
• Structured MCP results: every tool advertises an output schema and returns structuredContent plus readable JSON.
• Safe defaults: mutations are absent by default; destructive tools need a second opt-in and an exact target-specific confirmation string.
• Two modern transports: local stdio and stateless Streamable HTTP. Legacy HTTP+SSE is intentionally not carried forward.
• Defense in depth: response byte limits, request timeouts, HTTPS enforcement, token refresh, DNS-rebinding protection, exact origin checks, and constant-time MCP bearer checks.
• Cloud and self-hosted auth: Umami Cloud API keys, pre-issued self-hosted tokens, or lazy username/password login—including Umami v3.3+ two-factor verification—with a single refresh after 401.

Configure

From source

Requirements: Node.js 20 or newer.

npm install
npm run build
UMAMI_API_KEY=your-key node dist/cli.js

Example MCP client configuration:

{
  "mcpServers": {
    "umami": {
      "command": "npx",
      "args": ["-y", "@obsidiancorps/umami-mcp"],
      "env": {
        "UMAMI_API_KEY": "your-key",
        "UMAMI_DEFAULT_WEBSITE_ID": "optional-website-uuid"
      }
    }
  }
}

For a source checkout, replace the command with node and the arguments with the absolute path to dist/cli.js.

Authentication

Choose exactly one mode:

UMAMI_TWO_FACTOR_SECRET is the Base32 setup seed shown when enrolling an authenticator. The MCP generates a six-digit SHA-1 TOTP just-in-time and never logs or returns it. Because storing the password and TOTP seed together removes the separation between factors, use a dedicated least-privilege Umami account and protect its environment. A pre-issued UMAMI_TOKEN avoids retaining either credential.

UMAMI_TWO_FACTOR_CODE is only a one-off fallback; it expires quickly and is unsuitable for normal MCP startup. Configure only one two-factor variable.

Non-local plain HTTP Umami URLs are rejected. For an explicitly trusted private network only, set UMAMI_ALLOW_INSECURE_HTTP=true.

Tools

The default read-only set is:

Resources expose umami://capabilities and the live umami://websites list. Reusable prompts cover analytics review, conversion review, and realtime triage.

Time ranges

Most analytical tools accept either:

• period: last_24_hours, last_7_days, last_30_days, last_90_days, today, yesterday, this_week, last_week, this_month, or last_month; or
• both startAt and endAt as epoch milliseconds or ISO 8601 timestamps with an offset.

Calendar periods honor the supplied IANA timezone. Rolling periods retain the most recent data instead of rounding to midnight.

Mutations and destructive operations

No mutation tool is registered by default.

UMAMI_ENABLE_WRITE_TOOLS=true

This adds tools for creating/updating websites, segments, reports, boards/links/pixels, and sending analytics events. To additionally expose permanent reset/delete operations:

UMAMI_ENABLE_WRITE_TOOLS=true
UMAMI_ENABLE_DESTRUCTIVE_TOOLS=true

Destructive calls require confirmation strings such as RESET <website-id> or DELETE reports <report-id>. MCP annotations also identify these tools as destructive so supporting hosts can require approval.

Streamable HTTP

Loopback example:

MCP_TRANSPORT=http MCP_BEARER_TOKEN=replace-me npm start
# MCP:    http://127.0.0.1:3000/mcp
# Health: http://127.0.0.1:3000/health

For a container or non-loopback bind, both MCP_BEARER_TOKEN and MCP_ALLOWED_HOSTS are required:

docker build -t umami-mcp .
docker run --rm -p 3000:3000 \
  -e UMAMI_API_KEY=your-key \
  -e MCP_BEARER_TOKEN=long-random-secret \
  -e MCP_ALLOWED_HOSTS=mcp.example.com \
  umami-mcp

Set MCP_ALLOWED_ORIGINS to a comma-separated list of exact browser origins if browser-based MCP clients connect. Requests without an Origin header remain valid for native clients. Terminate TLS at a trusted reverse proxy; the built-in static bearer gate is suitable behind that boundary, not a replacement for OAuth on a public multi-user service.

Configuration reference

Development

npm install
npm test
npm run typecheck
npm run lint
npm run format:check
npm run build
npm run check

Tests drive the server through real in-memory, stdio, and Streamable HTTP MCP clients. See CONTRIBUTING.md and SECURITY.md before opening a change.

Compatibility baseline

• Umami: v3.3.1, with compatibility expected for late v3 releases exposing the documented routes.
• MCP SDK: TypeScript SDK v2.0.0.
• MCP protocol: 2026-07-28 plus the SDK's stateless compatibility path for 2025-era clients.
• Node.js: 20, 22, and 24.

Umami is a trademark of its respective owner. This independent integration is not affiliated with or endorsed by Umami Software.

License

Apache-2.0. See LICENSE.