Umami MCP server

MCP server exposing read-only analytics from the currentUmami Cloud APIandself-hosted Umami 3.x.

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

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

Choose exactly one authentication mode: a Cloud API keyorself-hosted username and password. Cloud API keys use the documentedAuthorization: Bearerscheme; standard self-hosted Umami 3.x does not support API keys.

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

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

- get_websites: return one page of websites.page >= 1and1 <= 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 <= 500and0 <= offset <= 10000.
- get_active: current active visitors.

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

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 areminute,hour,day,month, andyear. Timezones must be valid IANA names such asUTCorEurope/Rome. Comparisons areprevoryoy.

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

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 fordistinct_idand the UTM filters; the server serializes the upstream camelCase names automatically.

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 transient500,502,503, and504responses.Retry-Afteris 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.

On the current MCP revision, the statictools/listcatalog 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 withumami-mcp-server[otel], configure it externally, or disable it explicitly withOTEL_SDK_DISABLED=true. Seethe observability guidefor setup, exported names, redaction policy, and OTLP examples.

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

Connect Amazon Seller Central to Claude or ChatGPT via Two Minute Reports MCP and get accurate insights on orders, sales, inventory, and revenue performance.