umami — Claude Code MCP server: what it does, how to install
Connects Claude Code to Umami Analytics v3 for metrics, events, reports, and site management. Useful when an agent needs direct analytics access.
claude mcp add --env UMAMI_MODE=<UMAMI_MODE> --env UMAMI_URL=<UMAMI_URL> --env UMAMI_COLLECTOR_URL=<UMAMI_COLLECTOR_URL> --env UMAMI_USERNAME=<UMAMI_USERNAME> --env UMAMI_PASSWORD=<UMAMI_PASSWORD> --transport stdio umami -- npx -y @mikusnuz/umami-mcpWhat umami does
umami connects an MCP client to the Umami Analytics v3 API. Its tools cover website data, pageviews, events, sessions, metrics, reports, boards, segments, links, pixels, replay, exports, and revenue. It also exposes collection routes for sending events and performance data.
The server works with self-hosted Umami and Umami Cloud. Self-hosted login can use a username and password or an API key; Cloud uses an API key. Connection settings include UMAMI_URL, UMAMI_MODE, UMAMI_COLLECTOR_URL, and the relevant credentials.
It runs through @mikusnuz/umami-mcp with npx. Node.js 20 or newer is required. API-key authentication, session-property segments, and annotations require Umami 3.4 or later.
What it helps with
- read website metrics from Umami
- inspect pageviews and session data
- send events and performance information
- run analytics reports for a website
Example prompts for the agent
- Show me Umami statistics for this website and time range.
- Fetch pageviews and metrics for the site with this
websiteId. - Run an Umami report for funnel or retention data.
How to install umami
Platform CLI
claude mcp add --env UMAMI_MODE=<UMAMI_MODE> --env UMAMI_URL=<UMAMI_URL> --env UMAMI_COLLECTOR_URL=<UMAMI_COLLECTOR_URL> --env UMAMI_USERNAME=<UMAMI_USERNAME> --env UMAMI_PASSWORD=<UMAMI_PASSWORD> --transport stdio umami -- npx -y @mikusnuz/umami-mcpReplace <…> with your own values. 1 more environment variable is in the server README
Platform CLI
codex mcp add umami --env UMAMI_MODE=<UMAMI_MODE> --env UMAMI_URL=<UMAMI_URL> --env UMAMI_COLLECTOR_URL=<UMAMI_COLLECTOR_URL> --env UMAMI_USERNAME=<UMAMI_USERNAME> --env UMAMI_PASSWORD=<UMAMI_PASSWORD> -- npx -y @mikusnuz/umami-mcpReplace <…> with your own values. 1 more environment variable is in the server README
Config file
{
"mcpServers": {
"umami": {
"command": "npx",
"args": [
"-y",
"@mikusnuz/umami-mcp"
],
"env": {
"UMAMI_MODE": "<UMAMI_MODE>",
"UMAMI_URL": "<UMAMI_URL>",
"UMAMI_COLLECTOR_URL": "<UMAMI_COLLECTOR_URL>",
"UMAMI_USERNAME": "<UMAMI_USERNAME>",
"UMAMI_PASSWORD": "<UMAMI_PASSWORD>"
}
}
}
}Replace <…> with your own values. 1 more environment variable is in the server README
Config file
{
"servers": {
"umami": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@mikusnuz/umami-mcp"
],
"env": {
"UMAMI_MODE": "<UMAMI_MODE>",
"UMAMI_URL": "<UMAMI_URL>",
"UMAMI_COLLECTOR_URL": "<UMAMI_COLLECTOR_URL>",
"UMAMI_USERNAME": "<UMAMI_USERNAME>",
"UMAMI_PASSWORD": "<UMAMI_PASSWORD>"
}
}
}
}Replace <…> with your own values. 1 more environment variable is in the server README
Platform CLI
gemini mcp add -e UMAMI_MODE=<UMAMI_MODE> -e UMAMI_URL=<UMAMI_URL> -e UMAMI_COLLECTOR_URL=<UMAMI_COLLECTOR_URL> -e UMAMI_USERNAME=<UMAMI_USERNAME> -e UMAMI_PASSWORD=<UMAMI_PASSWORD> umami npx -y @mikusnuz/umami-mcpReplace <…> with your own values. 1 more environment variable is in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about umami
How do I install umami in Claude Code?
Run claude mcp add umami -e UMAMI_PASSWORD=<UMAMI_PASSWORD> -e UMAMI_API_KEY=<UMAMI_API_KEY> -- npx -y @mikusnuz/umami-mcp.
What does umami do?
It gives an AI coding client MCP access to Umami Analytics v3, including analytics, collection, reports, websites, and related management tools.
Which Umami versions does umami support?
A self-hosted instance must be compatible with Umami v3.3. API keys, session-property segments, and annotations require Umami 3.4 or later; Umami Cloud is supported too.
