Umami Mcp

Ask questions about your self-hosted Umami analytics without sending the data to another analytics SaaS.

A secure, model-friendly Model Context Protocol server for Umami Cloud and self-hosted Umami Analytics. It targets Umami v3.3.1 and the 2026-07-28 MCP protocol, while retaining compatibility with 2025-era MCP clients.

Install

Requirements: Node.js 20 or newer and one configured authentication mode.

npx -y @obsidiancorps/umami-mcp

Try asking:

• “Compare website traffic with last month.”
• “Which sources generated the most conversions?”
• “Find pages with poor Web Vitals.”

Agent skill

This repository also includes the Umami Analytics skill. The MCP server provides access to Umami; the skill guides an agent through traffic comparisons, conversion analysis, revenue, and performance investigations using those tools. It follows the Agent Skills format.

For MCP Market's Import from GitHub, use the skill folder URL:

https://github.com/ObsidianCorps/umami-mcp/tree/main/skills/umami-analytics

The URL must point to the folder containing SKILL.md. For a public repository, select Public repo. The folder must be pushed to main before the marketplace can import it.

For manual installation, copy skills/umami-analytics into your agent's skills directory (for example, .claude/skills/umami-analytics in a project). Configure and authenticate the MCP server separately; importing the skill does not install the server or grant access to analytics.

Why this implementation

• Current Umami v3 coverage: revenue APIs, session replay, heatmaps, event/session property pivots and typed series, segments, cohorts, boards, links, pixels, Web Vitals reports, and the established analytics APIs.
• Compact model surface: 17 read tools organize the API around analytical workflows instead of advertising dozens of near-duplicate endpoint tools.
• Model-friendly inputs: website names/domains resolve automatically, one accessible website is selected automatically, and date ranges accept presets or exact ISO/epoch timestamps.
• Structured MCP results: every tool advertises an output schema and returns structuredContent plus readable JSON.
• Safe defaults: mutations are absent by default; destructive tools need a second opt-in and an exact target-specific confirmation string.
• Two modern transports: local stdio and stateless Streamable HTTP. Legacy HTTP+SSE is intentionally not carried forward.
• Defense in depth: response byte limits, request timeouts, HTTPS enforcement, token refresh, DNS-rebinding protection, exact origin checks, and constant-time MCP bearer checks.
• Cloud and self-hosted auth: Umami Cloud API keys, pre-issued self-hosted tokens, or lazy username/password login—including Umami v3.3+ two-factor verification—with a single refresh after 401.

Configure

From source

Requirements: Node.js 20 or newer.

npm install
npm run build
UMAMI_API_KEY=your-key node dist/cli.js

Example MCP client configuration:

{
  "mcpServers": {
    "umami": {
      "command": "npx",
      "args": ["-y", "@obsidiancorps/umami-mcp"],
      "env": {
        "UMAMI_API_KEY": "your-key",
        "UMAMI_DEFAULT_WEBSITE_ID": "optional-website-uuid"
      }
    }
  }
}

For a source checkout, replace the command with node and the arguments with the absolute path to dist/cli.js.

Authentication

Choose exactly one mode: