Umami Compass

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.2 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.2. Never use the preview channel for an unattended production setup.

Umami Cloud

{

"mcpServers": { "umami": { "command": "npx", "args": ["--yes", "--prefer-online", "umami-compass@latest"], "env": { "UMAMI_API_KEY": "replace-with-your-api-key" } } } }

With UMAMI_API_KEY and no URL, the API root defaults to https://api.umami.is/v1.

Self-hosted Umami

{

"mcpServers": { "umami": { "command": "npx", "args": ["--yes", "--prefer-online", "umami-compass@latest"], "env": { "UMAMI_URL": "https://analytics.example.com", "UMAMI_USERNAME": "mcp-viewer", "UMAMI_PASSWORD": "replace-me", "UMAMI_WEBSITE_IDS": "6b2c8c10-908c-4a8e-a924-4049eb3bde8c" } } } }

UMAMI_URL is an instance origin; /api is appended. Use UMAMI_API_URL instead when a reverse proxy exposes a custom, exact API root.

UMAMI_WEBSITE_IDS is an optional safety allowlist, not a credential. Replace the example UUID with a website ID from Umami (or from list_websites), separate multiple IDs with commas, or remove the variable to discover every website visible directly or through a team membership.

UMAMI_TEAM_IDS is a strict team boundary for discovery and direct website/report access. When it is set, user-owned websites without one of the selected team IDs are excluded. If UMAMI_WEBSITE_IDS is also set, a website must pass both allowlists.

Do not commit real credentials. Prefer a dedicated view-only Umami account and the client/OS secret store when available.

Tools

The least-privilege default enables core,insights: eight primitive aggregate tools plus seven decision-ready aggregate workflows. Row-level events, sessions, replay, heatmaps, and other more sensitive modules remain opt-in.

Set UMAMI_TOOLSETS=all or a comma-separated subset. The default has 15 aggregate tools; all has 42. Multi-website insights are bounded to 50 websites with four concurrent website workers. High-cardinality report, performance, heatmap, channel fan-out, and activity results carry explicit limits and truncation metadata.

get_performance_breakdown requires at least 20 performance events per row by default for page, page-title, device, and browser rankings. This is an exploratory p75 quality guard, not a claim of statistical significance. Umami 3.2 calculates these counts with count(*), not count(metric), so Compass labels them as event counts and never presents them as metric-specific samples. Set minimumSampleCount explicitly to tighten the guard or lower it to 1 to include every otherwise valid row.

Umami 3.2 caps page, page-title, and browser candidates at 500 before Compass can apply the sample guard. Breakdown responses therefore report the effective minimum, excluded-row counts, candidate coverage, and whether that upstream cap may make the filtered ranking incomplete. If all complete candidates are undersized, emptyReason is insufficient_sample_size; if the candidate cap prevents that conclusion, dataStatus is unknown.

Successful tool responses preserve the existing data field and add a common meta envelope. Depending on the request it includes dataStatus, emptyReason, websiteId, requestedRange, and timezone. Truncation is split into responseTruncated for an incomplete primary result and sectionsTruncated for bounded nested sections; the aggregate truncated field remains for compatibility.

The server exposes umami://websites and the sanitized umami://capabilities resource. Website discovery returns only id, name, and domain; request get_website explicitly when detailed metadata is required. get_server_info returns the same local version, enabled toolsets, limits, and feature flags as a tool. Guided prompts cover an analytics report, weekly portfolio briefing, traffic investigation, release impact, tracking health, and conversion audit; each prompt is registered only when its required toolset is enabled. Scheduling a recurring briefing remains the MCP client's responsibility; the local stdio server does not run a background scheduler or send messages.

Performance analysis and upstream limits

analyze_performance_portfolio performs two bounded performance requests and two aggregate traffic requests per selected website, with four website workers. verbosity="compact" is the default decision summary; standard adds concise per-site rows and metric-specific drill-downs; full returns complete normalized per-site evidence. Drill-down websites are selected only by detailMetric. Performance events per pageview are returned as a ratio that may exceed 1; true collection coverage remains unknown_upstream because Umami does not return distinct covered pageviews. Portfolio p75 values are ranked but never averaged because percentiles from separate websites are not composable.

compare_web_vitals compares all five summary metrics. compare_performance_breakdown aligns page, title, device, or browser rows, returns comparable rows first, excludes rows below minimumSampleCount by default, and omits candidates whose absence is uncertain because an upstream top-500 list was capped. Set includeInsufficient=true to append undersized rows after useful comparisons. get_performance_cross_tab derives combinations through at most ten filtered fan-out requests and reports whether candidates came from performance events or traffic metrics. get_route_group_performance accepts caller-defined path regexes and queries every route group directly; route groups may overlap and PostgreSQL/ClickHouse regex dialect details can differ.

Performance tools accept only page/title and persisted environment filters that are consistent across Umami's supported database backends. excludeBounce, referrer, UTM, hostname, query, event, tag, and other non-persisted performance fields are rejected instead of ignored. In particular, Umami 3.2 builds but does not use its excludeBounce join in the performance report.

Umami 3.2 does not return metric-specific sample counts or counts in chart buckets. Compass therefore returns count: null for a chart point when the field is absent, includes sampleCounts.status="unavailable_upstream", and marks incomplete requested/current buckets with partial: true. Overall counts are named performanceEventCount. Non-CLS all-zero percentile placeholders are treated as unavailable; a zero CLS remains valid.

LCP decomposition, LCP element/resource attribution, cache status, and edge region are explicitly reported as unavailable because Umami's aggregate performance report does not collect or expose them. Compass does not infer a decomposition by subtracting unrelated aggregate percentiles.

Filters, direct traffic, channels, and traffic quality

Plain string filters remain compatible. Structured filters add equals, not_equals, contains, not_contains, regex, not_regex, is_empty, and `is_no