Umami MCP Server

MCP server exposing read-only analytics from the current Umami Cloud API and self-hosted Umami 3.x.

Support matrix

The /v1 suffix belongs to the current Cloud API URL. It does not mean that this server supports version 1 of the self-hosted Umami application.

Requirements and run command

• Python 3.11+
• uv

Run the published package directly:

uvx umami-mcp-server

Configuration

Environment variables:

• UMAMI_API_KEY: Cloud or self-hosted API key.
• UMAMI_USERNAME: self-hosted Umami 3.x username.
• UMAMI_PASSWORD: self-hosted Umami 3.x password.
• UMAMI_API_BASE: optional; defaults to https://api.umami.is/v1. For self-hosted deployments, set the API root including /api.

Choose exactly one authentication mode: API key or username and password. Cloud accepts only an API key.

Example MCP configuration for Cloud:

{
  "mcp": {
    "umami": {
      "type": "local",
      "command": ["uvx", "umami-mcp-server"],
      "environment": {
        "UMAMI_API_KEY": "YOUR_UMAMI_CLOUD_API_KEY",
        "UMAMI_API_BASE": "https://api.umami.is/v1"
      },
      "enabled": true
    }
  }
}

Self-hosted Umami 3.x:

{
  "mcp": {
    "umami": {
      "type": "local",
      "command": ["uvx", "umami-mcp-server"],
      "environment": {
        "UMAMI_USERNAME": "YOUR_USERNAME",
        "UMAMI_PASSWORD": "YOUR_PASSWORD",
        "UMAMI_API_BASE": "https://your-umami.example/api"
      },
      "enabled": true
    }
  }
}

Tools

• get_websites: return one page of websites. page >= 1 and 1 <= page_size <= 100.
• get_stats: summary pageviews, visitors, visits, bounces, total time, and comparison.
• get_pageviews: pageview and session time series.
• get_metrics: compact or expanded metrics. 1 <= limit <= 500 and 0 <= offset <= 10000.
• get_active: current active visitors.

Every website_id, segment, and cohort identifier is validated as a UUID before an HTTP request is sent.

Time ranges

Datetime parameters accept ISO datetimes. Naive values are interpreted as UTC. The four range rules are:

The end must be later than the start. Pageview units are minute, hour, day, month, and year. Timezones must be valid IANA names such as UTC or Europe/Rome. Comparisons are prev or yoy.

Metrics and filters

Metric types:

path, fullPath, entry, exit, referrer, domain, title, query,
event, tag, hostname, utmSource, utmMedium, utmCampaign,
utmContent, utmTerm, browser, os, device, screen, language,
country, city, region, distinctId, channel

Documented Umami 3 filters:

path, referrer, title, query, browser, os, device, country,
region, city, language, hostname, tag, event, distinctId,
utmSource, utmMedium, utmCampaign, utmContent, utmTerm,
segment, cohort

Tool input uses snake_case for distinct_id and the UTM filters; the server serializes the upstream camelCase names automatically.

Reliability and safe errors

One HTTP client and connection pool is shared for the MCP server lifespan. Login-mode tokens are shared, concurrent login/refresh is synchronized, and a request can perform at most three analytics sends and one token refresh. GET requests retry only network failures, timeouts, rate limits, and transient 500, 502, 503, and 504 responses. Retry-After is honored up to 60 seconds.

Errors are exposed as controlled categories: authentication, rate limit, timeout, network, upstream failure, and invalid response. Public messages and logs exclude response bodies, credentials, headers, complete query URLs, and raw HTTP/Pydantic exception values.

Cache and observability

On the current MCP revision, the static tools/list catalog has a public five-minute cache hint. Tool order and schema content are deterministic, and the catalog contains no Umami data, website IDs, or credentials. Legacy protocol serialization remains unchanged and does not include cache fields.

MCP SDK already traces incoming MCP operations. Umami MCP Server adds a child span for each logical Umami analytics request, a child login span when needed, and metrics for duration, errors, retries, rate limits, and token refreshes. Only W3C Trace Context is propagated to Umami; MCP baggage is not forwarded.

The base package uses only the OpenTelemetry API, so instrumentation remains no-op without an SDK and exporter. Install the optional stack with umami-mcp-server[otel], configure it externally, or disable it explicitly with OTEL_SDK_DISABLED=true. See the observability guide for setup, exported names, redaction policy, and OTLP examples.

Development

uv sync --dev
uv run ruff format . --check
uv run ruff check .
uv run pyright
uv run pytest

The optional live Cloud contract test requires UMAMI_LIVE_CLOUD_API_KEY and UMAMI_LIVE_CLOUD_WEBSITE_ID; UMAMI_LIVE_CLOUD_API_BASE may override the default Cloud root.