Umami MCP Server
Provides tools for interacting with Umami Analytics (both Cloud and self-hosted instances) to retrieve website lists, summary statistics, time-series pageview data, metric breakdowns (by URL, referrer, browser, etc.), and real-time active visitor counts.
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., "@Umami MCP Server How many active visitors are on my website right now?"
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.
Umami MCP Server
An MCP server for Umami Analytics — works with both Umami Cloud and self-hosted instances.
Zero dependencies. No cloning, no install steps — just point your MCP client at it.
Why?
Existing Umami MCP servers either don't support Umami Cloud (which uses API key auth, not username/password) or are broken and bloated (torch, faiss, sentence-transformers for… analytics?).
This server talks to the Umami API and exposes 5 tools over MCP. Pure Python, zero dependencies.
Related MCP server: Plausible Analytics MCP Server
Tools
Tool | Description |
| List all tracked websites |
| Summary stats: pageviews, visitors, visits, bounces, totaltime (seconds) |
| Time-series pageview/session data (unit: minute/hour/day/month/year; timezone: IANA, e.g. UTC) |
| Breakdown by type: path/url/entry/exit/referrer/domain/title/query/event/tag/hostname/browser/os/device/screen/language/country/region/city/channel |
| Number of currently active visitors (last 5 minutes) |
Quick Start
1. Get your credentials
Umami Cloud: Go to Settings → API Keys in your Umami Cloud dashboard and create an API key.
Self-hosted: Use the username and password you log in with.
2. Add to your MCP client
No cloning required — uvx fetches and runs it directly from GitHub.
Requires
uv. Install with:curl -LsSf https://astral.sh/uv/install.sh | sh
Claude Desktop / Claude Code
Add to your MCP config (~/.claude.json, Claude Desktop settings, etc.):
Umami Cloud:
{
"mcpServers": {
"umami": {
"command": "uvx",
"args": ["--from", "git+https://github.com/lukasschmit/umami-mcp", "umami-mcp"],
"env": {
"UMAMI_URL": "https://api.umami.is",
"UMAMI_API_KEY": "your_api_key_here"
}
}
}
}Self-hosted:
{
"mcpServers": {
"umami": {
"command": "uvx",
"args": ["--from", "git+https://github.com/lukasschmit/umami-mcp", "umami-mcp"],
"env": {
"UMAMI_URL": "https://your-umami-instance.com",
"UMAMI_USERNAME": "admin",
"UMAMI_PASSWORD": "your_password"
}
}
}
}Cursor
Add to .cursor/mcp.json in your project root (or global settings):
{
"mcpServers": {
"umami": {
"command": "uvx",
"args": ["--from", "git+https://github.com/lukasschmit/umami-mcp", "umami-mcp"],
"env": {
"UMAMI_URL": "https://api.umami.is",
"UMAMI_API_KEY": "your_api_key_here"
}
}
}
}VS Code (Copilot)
Add to your VS Code settings.json:
{
"mcp": {
"servers": {
"umami": {
"command": "uvx",
"args": ["--from", "git+https://github.com/lukasschmit/umami-mcp", "umami-mcp"],
"env": {
"UMAMI_URL": "https://api.umami.is",
"UMAMI_API_KEY": "your_api_key_here"
}
}
}
}
}BoltAI
Go to Settings → MCP Servers → Add Server, then enter:
Command:
uvxArguments:
--from git+https://github.com/lukasschmit/umami-mcp umami-mcpEnvironment Variables:
UMAMI_URL=https://api.umami.isUMAMI_API_KEY=your_api_key_here
Environment Variables
Variable | Required | Description |
| Self-hosted: Yes, Cloud: Optional | Base URL — defaults to |
| Cloud | API key from Umami Cloud dashboard |
| Self-hosted | Login username |
| Self-hosted | Login password |
| Optional | Cloudflare Access service token client ID (for protected self-hosted APIs) |
| Optional | Cloudflare Access service token secret |
| Optional | Custom User-Agent for outbound requests (default: |
| Optional | Set to |
Set either UMAMI_API_KEY (Cloud) or both UMAMI_USERNAME + UMAMI_PASSWORD (self-hosted). The server auto-detects which mode to use.
For convenience, UMAMI_URL may include /v1 (Cloud) or /api (self-hosted); suffixes are normalized automatically.
If your self-hosted Umami is behind Cloudflare Access, set both UMAMI_CF_ACCESS_CLIENT_ID and UMAMI_CF_ACCESS_CLIENT_SECRET so machine-to-machine MCP calls can pass Access checks.
get_metrics accepts both type="path" and type="url" for compatibility across Umami versions.
startAt and endAt accept Unix-millisecond integers or numeric strings from MCP clients.
For time-based tools, you can use range instead of raw timestamps:
last_24h, last_7d, last_30d, this_month, last_month.
compare supports prev (previous period, same length) and yoy (year-over-year).
Usage Examples
Once connected, you can ask your AI assistant things like:
"What are my top pages this week?"
"Show me visitor trends for the last 30 days"
"Which countries are my visitors from?"
"How many people are on my site right now?"
"Compare this month's traffic to last month"
The assistant will call the appropriate tools with the right parameters.
How It Works
The server implements the Model Context Protocol over stdio (JSON-RPC, one JSON object per line). When an MCP client starts it, the server:
Reads JSON-RPC messages from stdin
Handles
initialize,tools/list, andtools/callmethodsMakes authenticated HTTP requests to the Umami API
Returns results as JSON text content
No background processes, no polling, no state beyond the auth token.
License
MIT
Available Tools
5 toolsget_activeB
Get the number of currently active visitors on a website (last 5 minutes).
Inputs: websiteId (required).
get_metricsC
Get a breakdown of metrics by a given dimension (url, referrer, browser, os, device, country, event, etc.) for a website.
Inputs: websiteId (required), startAt (required), endAt (required), type (required), +16 more.
get_pageviewsC
Get time-series pageview and session data for a website, bucketed by the chosen time unit.
Inputs: websiteId (required), startAt (required), endAt (required), unit (required), +16 more.
get_statsB
Get summary statistics (pageviews, visitors, visits, bounces, totaltime) for a website over a date range. Timestamps are Unix milliseconds.
Inputs: websiteId (required), startAt (required), endAt (required), compare, +14 more.
get_websitesC
List all tracked websites in your Umami account.
Inputs: search, page, pageSize, includeTeams.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a clearly distinct purpose: get_active focuses on real-time visitor counts, get_metrics provides dimensional breakdowns, get_pageviews offers time-series data, get_stats gives summary statistics, and get_websites lists available websites. There is no overlap or ambiguity in their functions.
All tool names follow a consistent verb_noun pattern with 'get_' as the prefix (e.g., get_active, get_metrics, get_pageviews, get_stats, get_websites). This uniformity makes the set predictable and easy to understand.
With 5 tools, this server is well-scoped for analytics purposes, covering key aspects like real-time data, metrics, time-series, summaries, and website listing. Each tool earns its place without feeling excessive or insufficient.
The toolset provides strong coverage for querying analytics data, including active visitors, detailed metrics, pageviews, stats, and websites. A minor gap is the lack of tools for configuration or management (e.g., adding websites or events), but agents can effectively work with the provided read-only operations.
Maintenance
Related MCP Connectors
Privacy-first, cookie-free web analytics. Read stats and manage sites from your AI.
Read-only website analytics, traffic statistics, and realtime insights from BetterUmami.
Privacy-first web analytics. Query pageviews, referrers, trends, and AI insights.
SEO & marketing toolkit for AI agents: GA4, Search Console, AdSense, GTM, PageSpeed, Trends.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnhances Claude's capabilities by providing access to website analytics data from Umami, enabling analysis of user behavior, website performance tracking, and data-driven insights generation.9MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to query website statistics from Plausible Analytics, providing access to metrics like real-time visitors, traffic trends, and page performance. It supports both Plausible Cloud and self-hosted instances through the Stats API v2.642 npm1MIT
- AlicenseNot gradedqualityBmaintenanceExposes Umami analytics (Cloud or self-hosted) as read-only tools for querying website stats, pageviews, metrics, and active visitors.4,000 npmMIT
- AlicenseAqualityCmaintenanceEnables natural-language analytics against Umami, including traffic stats, time series, sessions, custom events, and filtered breakdowns, plus self-hosted admin CRUD for websites, users, and teams, and client onboarding.4812 npm1MIT