Umami MCP Server
This server provides read-only access to Umami analytics (Cloud and self-hosted 3.x) with tools to:
Get Websites: List tracked websites with search, pagination, and team filtering.
Get Stats: Retrieve summary statistics (pageviews, visitors, visits, bounces, total time) with comparison options.
Get Pageviews: Fetch time series data for pageviews and sessions, with granularity (hour, day, month, year) and comparisons.
Get Metrics: Query detailed metrics by dimensions (e.g., browser, country, referrer, UTMs) with pagination and filters.
Get Active: See current active visitors.
All tools support extensive filters (path, referrer, browser, country, OS, etc.), flexible time ranges, and optional comparisons. Authentication supports API key (Cloud) or username/password (self-hosted). The server includes caching, retries, rate limiting, and error handling for reliability.
Provides tools to interact with Umami Cloud and self-hosted analytics, allowing for listing websites, retrieving visitor statistics, tracking page traffic over time, analyzing device and geographic metrics, and monitoring real-time active visitors.
Umami MCP Server
MCP server exposing read-only analytics from the current Umami Cloud API and self-hosted Umami 3.x.
Support matrix
Deployment | Support | API root | Authentication |
Umami Cloud (current) | Supported |
| API key |
Self-hosted Umami 3.x | Supported |
| Username/password |
Self-hosted Umami 2.x | Not supported; any future integration will be separate | — | — |
Umami 1.x | Not supported | — | — |
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.
Related MCP server: Umami MCP Server
Requirements and run command
Python 3.11+
Run the published package directly:
uvx umami-mcp-serverConfiguration
Environment variables:
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 key or self-hosted username and
password. Cloud API keys use the documented Authorization: Bearer scheme; standard
self-hosted Umami 3.x does not support API keys.
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 >= 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.
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:
Inputs | Range |
neither | now minus seven days → now |
only | seven days before |
only |
|
both | explicit range |
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, channelDocumented Umami 3 filters:
path, referrer, title, query, browser, os, device, country,
region, city, language, hostname, tag, event, distinctId,
utmSource, utmMedium, utmCampaign, utmContent, utmTerm,
segment, cohortTool 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 pytestThe 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.
Available Tools
5 toolsget_activeD
Current active visitors.
Inputs: website_id (required). Returns: object
get_metricsD
See browsers, countries, devices, and more.
Inputs: website_id (required), type (required), start_at, end_at, +4 more. Returns: result
get_pageviewsC
View page traffic over time.
Inputs: website_id (required), start_at, end_at, unit, +3 more. Returns: object
get_statsD
Get visitor statistics.
Inputs: website_id (required), start_at, end_at, filters. Returns: object
get_websitesC
List all your websites.
Inputs: include_teams, search, page, page_size. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
The tools have some overlap in purpose, particularly 'get_metrics' and 'get_stats', which both seem to cover visitor statistics, and 'get_active' could be confused as part of metrics or stats. However, descriptions help differentiate 'get_pageviews' and 'get_websites' as more specific functions, reducing ambiguity.
All tool names follow a consistent 'get_' verb_noun pattern, such as 'get_active', 'get_metrics', 'get_pageviews', 'get_stats', and 'get_websites'. This predictable naming convention makes the set easy to understand and navigate.
With 5 tools, the count is reasonable for a web analytics server, covering core functions like active visitors, metrics, pageviews, stats, and websites. It's slightly thin but well-scoped, as each tool appears to serve a distinct aspect of the domain without being overwhelming.
The toolset covers key read operations for web analytics, such as retrieving active visitors, metrics, pageviews, stats, and websites. However, there are notable gaps in CRUD coverage, such as missing create, update, or delete operations for websites or other entities, which could limit agent workflows for managing analytics data.
Related MCP Connectors
Hosted MCP server for GA4, Google Ads and Search Console. Google OAuth, nothing to install.
Hosted MCP server for Google Ads and LinkedIn Ads analysis.
MCP server for querying and analyzing data from ad platforms, analytics tools, and spreadsheets
Related MCP Servers
- AlicenseCqualityBmaintenanceFull-coverage MCP server for Umami Analytics API v2 — 66 tools for website analytics, stats, events, and team management133121 npm8MIT
- AlicenseAqualityDmaintenanceRead-only MCP server for Umami analytics. It talks to the Umami REST API directly over HTTP, supporting self-hosted and cloud setups.88 npmMIT
- AlicenseAqualityCmaintenanceAn MCP server that gives Claude read access to Umami web analytics, allowing natural language queries for stats, breakdowns, pageview trends, live visitors, and user journeys.101MIT
- AlicenseAqualityDmaintenanceA security-first MCP server for Umami analytics (Cloud and self-hosted v3) enabling analytics, reporting, and administration with least privilege and credential-safe design.328 npmMIT