Umami Compass

Open-source MCP server for Umami Analytics — Cloud and self-hosted.

Distribution: umami-compass on npm · io.github.webcredo/umami-compass in the official MCP Registry

Umami Compass is a secure, read-only Model Context Protocol server for Umami Analytics. It gives MCP clients accurate Umami 3.2 analytics without exposing a database or allowing arbitrary network requests.

Version 0.5.1 is the current source release. See Compatibility before using it with older Umami versions.

The npx examples follow the stable npm release channel and check it whenever the MCP process starts. For source-based evaluation, clone this repository, run pnpm install --frozen-lockfile && pnpm build, and use node /absolute/path/to/umami-compass/dist/cli.js as the MCP command.

Why this project

Existing Umami MCP servers each cover part of the problem, but our July 2026 review found gaps around Umami 3.2 response correctness, Cloud authentication, safety boundaries, or extensibility. Umami Compass sets a higher, testable quality bar:

• Correct auth for both products: x-umami-api-key for Umami Cloud and Bearer/login auth for self-hosted instances.
• Umami 3.2-aware responses, including both pageviews and sessions, Core Web Vitals, funnels, journeys, attribution, retention, revenue, bounded heatmaps, and replay metadata.
• Read-only by construction: every tool declares MCP safety annotations; no create, update, delete, raw HTML, or arbitrary URL tool exists.
• Defense in depth: fixed upstream origin, HTTPS policy, website and team allowlists, range/page/response-byte caps, request timeout, cancellation propagation, and redacted errors.
• Decision-ready insights: bounded traffic and performance portfolio overviews, traffic-change evidence, release-impact analysis, tracking-health audits, and website resolution without arbitrary API access.
• Agent-friendly output: machine-readable structuredContent, a common status/range/truncation envelope, two resources, and six guided prompts.
• Contributor-friendly architecture: endpoint modules, dependency-injected HTTP, a central access policy, ADRs, and real MCP integration tests.

See the dated landscape review for the evidence and methodology.

Quick start

Requirements: Node.js 22 or newer and an Umami identity with view-only access where possible.

The examples use the auto-updating stable launcher:

npx --yes --prefer-online umami-compass@latest

@latest selects the stable npm channel and --prefer-online makes npm check the registry even when package metadata is cached. npm still reuses the cached package when that exact release is already present. Updates take effect the next time the MCP process starts; an already running local server cannot replace itself.

Use umami-compass@next instead to opt into preview releases. For reproducible CI or centrally managed environments, pin an exact release and omit the online check, for example npx --yes umami-compass@0.5.1. Never use the preview channel for an unattended producti

... View full README on GitHub