@rampstack/umami-mcp
This server lets you query Umami Cloud website analytics data from MCP clients (like Claude) in a read-only fashion.
Capabilities:
List Websites (
list_websites): Retrieve all websites on your Umami account (id, name, domain), optionally including team-owned sites — use this first to discover validwebsite_idvalues.Get Summary Stats (
get_stats): Fetch aggregate metrics (visitors, visits, pageviews, bounces, total time) for a website over a custom time window, including previous-period comparisons and computed deltas. Supports optional filters by URL, country, and referrer.Get Pageviews Timeseries (
get_pageviews): Retrieve pageviews and sessions as a time series bucketed by day or hour over a specified window, with optional country and referrer filters.Get Top Metrics by Dimension (
get_metrics): Query the top values for a specific dimension — URLs, referrers, browsers, operating systems, devices, countries, or events — returning ranked results with visitor counts.Get Custom Event Data (
get_event_data): Access custom event-data properties collected over a time window (optionally filtered to a specific event name); availability depends on your Umami plan.Cohort Report (
cohort_report): Run a single combined query returning stats with deltas + top 10 URLs + top 10 referrers + top 10 events for a website, using convenient shorthand ranges (24h,7d,30d,90d) or a custom ISO date range.
Read-only integration with Umami Cloud analytics, providing tools to list websites, retrieve statistics, pageviews, metrics, event data, and cohort reports.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@@rampstack/umami-mcp Show me the stats for my website"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@rampstack/umami-mcp
A read-only Model Context Protocol server for Umami Cloud analytics. It exposes your Umami website data to MCP clients (Claude Code, Claude Desktop, and others) as a small set of GET-only tools.
Read-only by construction: the server makes exactly one kind of network call, an authenticated HTTP GET against the Umami Cloud API. There is no write path in the code, so no tool can create, edit, or delete anything in your Umami account.
Install
One line for Claude Code (user scope):
claude mcp add umami --scope user \
--env UMAMI_API_KEY=your_key_here \
-- npx -y @rampstack/umami-mcpClaude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"umami": {
"command": "npx",
"args": ["-y", "@rampstack/umami-mcp"],
"env": {
"UMAMI_API_KEY": "your_key_here"
}
}
}
}Environment
Variable | Required | Default | Notes |
| yes | none | Umami Cloud API key. The server exits if missing. |
| no |
| Override for a regional base, e.g. |
Get a key from the Umami Cloud dashboard under Settings -> API keys. The key
is passed to Umami in the x-umami-api-key header
(docs).
Related MCP server: umami-mcp-server
Tools
All tools take dates as ISO 8601 or epoch milliseconds. Naive datetimes (no
timezone) are treated as UTC. Every time-scoped response echoes the resolved
{ startAt, endAt } epoch window so you can verify the exact window queried.
Tool | Purpose |
| id, name, domain for every site on the account. Call first to get |
| visitors, visits, pageviews, bounces, totaltime + previous period + computed deltas. |
| pageviews/sessions timeseries, bucketed by |
| top values for one dimension ( |
| custom event-data properties (plan-gated; see below). |
| one call: stats + top 10 urls + top 10 referrers + top 10 events over a range. |
cohort_report accepts a range of 24h, 7d, 30d, 90d, or an ISO
start/end pair like 2026-01-01/2026-02-01.
Note on metric types
Umami's current docs label the URL dimension path. This server exposes it as
url, the long-standing alias the API still accepts, matching the Umami web UI
vocabulary. Other dimensions (referrer, browser, os, device, country,
event) map directly.
Note on event-data
The get_event_data tool calls the Umami event-data endpoints, which are gated
by account plan. On tiers where they are not exposed, the tool returns a clear
note (not fabricated data) and points you to get_metrics with type=event for
event counts, which is available everywhere.
Troubleshooting
Every call fails with "Network error reaching Umami" / fetch failed. The
server never reached the Umami API — this is a transport error, not an API
response. Check the unwrapped cause code in the message:
UNABLE_TO_VERIFY_LEAF_SIGNATURE(or another certificate error) means a TLS interceptor — antivirus (e.g. AVG, Kaspersky) or a corporate proxy (Zscaler, Netskope) — is re-signing HTTPS with a root CA that lives in the OS trust store. Node ships its own CA bundle and ignores the OS store by default, so it rejects the chain. Fix it by telling Node to trust the OS store:claude mcp add umami --scope user -- node --use-system-ca /path/to/dist/index.js--use-system-ca(Node 20.6+/22+) trusts the Windows/macOS certificate store where the interceptor's root CA is installed. Prefer this over exporting the CA by hand, and never disable verification withNODE_TLS_REJECT_UNAUTHORIZED=0— that would send your API key over an unverified connection.ENOTFOUND/ECONNREFUSED/ETIMEDOUTpoint at DNS or connectivity to the configuredUMAMI_API_BASE, not a certificate problem.
Security
Read-only by construction. The client exposes a single
get()method; there is no POST/PUT/DELETE anywhere in the source.GET-only. Every tool maps to a documented Umami GET endpoint.
Key stays local.
UMAMI_API_KEYis read from your environment and sent only in thex-umami-api-keyrequest header. It is never logged, never written to disk, and never included in error messages.No telemetry. The server makes no calls other than to the Umami API base you configure.
MIT licensed.
The Umami Cloud API key has account-wide read scope. If you manage analytics for multiple clients, use a separate Umami team or account per client rather than one key that can read them all.
Development
Requires Node 20+.
npm install
npm run build # tsc -> dist/
npm test # compiles and runs the node:test suite (mocked fetch, no live API)Tests never make live API calls and never reference a real key.
Publishing
This package is not yet published. To publish (maintainer action):
npm run build
npm publish --access publicLicense
MIT. See LICENSE.
Available Tools
6 toolscohort_reportC
One-call snapshot for a website: stats (with deltas) plus top 10 URLs, top 10 referrers, and top 10 events, over a range.
Inputs: range (required), website_id (required), country.
get_event_dataA
Custom event-data properties collected over a window, optionally for one event name. Requires an Umami plan that exposes the event-data endpoints; returns a clear note if unavailable. For simple event counts use get_metrics with type=event.
Inputs: end (required), start (required), website_id (required), event_name.
get_metricsA
Top values for one dimension over a window (e.g. top URLs, referrers, browsers). Returns [{ x: value, y: visitors }].
Inputs: end (required), type (required), start (required), website_id (required), +3 more.
get_pageviewsA
Pageviews and sessions as a timeseries over a window, bucketed by day or hour.
Inputs: end (required), start (required), website_id (required), unit, +2 more.
get_statsA
Summary stats for a website over a window: visitors, visits, pageviews, bounces, totaltime, plus the previous period's values and computed deltas.
Inputs: end (required), start (required), website_id (required), url, +2 more.
list_websitesA
List every website on the Umami account: id, name, and domain. Call this first to discover valid website_id values for the other tools.
Inputs: include_teams.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a clearly distinct purpose: listing websites, summary stats, pageview timeseries, top dimension values, custom event data, and a combined cohort report. Overlap is minimal and descriptions clarify boundaries.
Most tools follow the 'verb_noun' pattern (list_websites, get_stats, get_pageviews, get_metrics, get_event_data), but 'cohort_report' breaks the pattern with a noun_noun format, causing a minor inconsistency.
With 6 tools, the server is well-scoped for an analytics API. Each tool serves a distinct analysis need without redundancy or bloat.
The tool set covers all core analytics queries: listing websites, aggregate stats, timeseries pageviews, top metrics, event data, and a combined snapshot. No obvious gaps for read-only analytics.
Related MCP Connectors
Read-only Google Analytics 4 MCP server for AI assistants.
MCP server for querying and analyzing data from ad platforms, analytics tools, and spreadsheets
Hosted MCP server for GA4, Google Ads and Search Console. Google OAuth, nothing to install.
Read-only website analytics, traffic statistics, and realtime insights from BetterUmami.
Related MCP Servers
- FlicenseAqualityDmaintenanceRead-only MCP server for Umami analytics. It talks to the Umami REST API directly over HTTP, supporting self-hosted and cloud setups.8-
- 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
- AlicenseNot gradedqualityDmaintenanceMCP server for Umami Analytics that provides read-only tools to query website stats, events, sessions, reports, and more, enabling natural language analytics queries.12 npm3MIT
- 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