umami-analytics-mcp

Security-first Model Context Protocol server for Umami analytics — Umami Cloud and self-hosted (v3). Set up, analyze, report on, and (when you allow it) administer your Umami instance from any MCP client.

• 🚀 Local-first — npx umami-analytics-mcp, zero build step, ~2 runtime deps.
• ☁️ Or host it — deploy to Vercel (one Web function) or run the bundled Docker HTTP server. One shared core, three transports.
• 🔒 Credential-safe — secrets live in env only; never placed in tool arguments, outputs, or logs (two-layer redaction). Remote endpoints are bearer-gated and fail closed.
• 🎚️ Least privilege — read-only by default; write and admin tiers are opt-in; destructive ops (delete/reset) are double-gated.
• 📊 Comprehensive — full Umami v3 surface: stats, metrics, events, sessions, reports (funnel, retention, journey, attribution, revenue, UTM, web-vitals), segments, teams, share links, event ingestion, and self-hosted user administration.

---

Contents

• Quickstart (local / npx)
• Configuration
• Capability tiers
• MCP client setup
• Remote hosting · Vercel · Docker / self-host
• Security model
• Tool reference
• Prompts & resources
• Development

---

Quickstart (local / npx)

No install required. Point your MCP client at:

npx -y umami-analytics-mcp

…with credentials supplied via environment variables. For Umami Cloud, create an API key at Dashboard → Settings → API keys and set UMAMI_API_KEY. For self-hosted, set UMAMI_API_URL + UMAMI_USERNAME + UMAMI_PASSWORD. See MCP client setup for copy-paste configs.

By default the server is read-only (32 analytics tools). Opt into writes/admin explicitly — see Capability tiers.

---

Configuration

All configuration is via environment variables (secrets) and optional CLI flags (non-secrets).

Variable	Mode	Description
UMAMI_API_KEY	Cloud	Umami Cloud API key (selects Cloud mode).
UMAMI_CLOUD_REGION	Cloud	us or eu (optional regional base URL).
UMAMI_API_URL	self-hosted	Instance base URL, e.g. https://stats.example.com (/api appended).
UMAMI_USERNAME / UMAMI_PASSWORD	self-hosted	Login credentials → bearer token (cached, auto-renewed on 401).
UMAMI_TEAM_ID	both	Scope website listings to a team (optional).
UMAMI_DEFAULT_TIMEZONE	both	IANA tz for time-series tools (default UTC).
UMAMI_ENABLE_WRITE	both	1 to expose create/update + send_event tools.
UMAMI_ENABLE_ADMIN	both	1 to expose user-management tools (self-hosted only).
UMAMI_ALLOW_DESTRUCTIVE	both	1 — also required to expose delete/reset tools.
MCP_AUTH_TOKEN	remote	Shared-secret bearer required by the Vercel/HTTP endpoints.

Self-hosted instances that issue API keys can use UMAMI_API_URL + UMAMI_API_KEY instead of username/password.

Surrounding quotes are stripped from values defensively. For local use you can keep settings in a file and load them with --env-file:

npx umami-analytics-mcp --env-file .env.local

Run npx umami-analytics-mcp --help for the full flag list.

---

Capability tiers

The server exposes only the tools for the tiers you enable, layered on top of Umami's own role-based access (the API still enforces your account's real permissions — tiers just decide which tools are even visible).

Tier	Enable with	Adds	Example tools
read	(always on)	analytics & reporting	get_stats, get_metrics, report_funnel, list_sessions
write	UMAMI_ENABLE_WRITE=1	mutations + ingestion	create_website, send_event, add_team_member
admin	UMAMI_ENABLE_ADMIN=1 (self-hosted)	user administration	create_user, set_user_role
destructive	UMAMI_ALLOW_DESTRUCTIVE=1 (+ write/admin)	delete / reset	delete_website, reset_website, delete_user

Tool counts: 32 read → 46 with write → 52 with destructive → 58 at full tier on self-hosted. On Cloud the admin tier is automatically disabled (Umami Cloud has no user-admin API) and the server explains why at startup. Destructive tools carry MCP destructiveHint annotations so clients can warn before running them.

---

MCP client setup

Claude Desktop / Cursor (claude_desktop_config.json / .cursor/mcp.json)

{
  "mcpServers": {
    "umami": {
      "command": "npx",
      "args": ["-y", "umami-analytics-mcp"],
      "env": {
        "UMAMI_API_KEY": "your_cloud_api_key"
        // self-hosted instead:
        // "UMAMI_API_URL": "https://stats.example.com",
        // "UMAMI_USERNAME": "admin",
        // "UMAMI_PASSWORD": "••••••",
        // opt into writes:
        // "UMAMI_ENABLE_WRITE": "1"
      }
    }
  }
}

Claude Code

claude mcp add umami \
  -e UMAMI_API_KEY=your_cloud_api_key \
  -- npx -y umami-analytics-mcp

VS Code (.vscode/mcp.json)

{
  "servers": {
    "umami": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "umami-analytics-mcp"],
      "env": { "UMAMI_API_KEY": "your_cloud_api_key" }
    }
  }
}

---

Remote hosting

Both remote transports require MCP_AUTH_TOKEN; without it they reject every request (fail closed). Clients authenticate with Authorization: Bearer <MCP_AUTH_TOKEN>.

Deploy to Vercel

The repo ships a single Web function at api/mcp.ts (no Next.js required).

1. Push this repo to GitHub and Import it in Vercel.
2. Set Environment Variables: your Umami credentials (UMAMI_API_KEY or UMAMI_API_URL+UMAMI_USERNAME+UMAMI_PASSWORD), optional tier flags, and a strong MCP_AUTH_TOKEN.
3. Deploy. Your endpoint is https://<deployment>.vercel.app/api/mcp.
4. Harden: enable Vercel Deployment Protection (locks preview URLs) and Firewall.

Connect a Streamable-HTTP-capable client to the URL with the bearer header. stdio-only clients bridge via:

npx mcp-remote https://<deployment>.vercel.app/api/mcp \
  --header "Authorization: Bearer $MCP_AUTH_TOKEN"

Docker / self-host

Runs the framework-free standalone HTTP server (umami-mcp-http):

docker build -t umami-mcp .
docker run --rm -p 8787:8787 \
  -e UMAMI_API_KEY=your_cloud_api_key \
  -e MCP_AUTH_TOKEN=$(openssl rand -hex 32) \
  umami-mcp
# → endpoint at http://localhost:8787/mcp  (health: /health)

Or without Docker: MCP_AUTH_TOKEN=… UMAMI_API_KEY=… npx -y umami-analytics-mcp umami-mcp-http (bin umami-mcp-http). Set HOST, PORT, optional MCP_ALLOWED_HOSTS (enables DNS-rebinding protection), or MCP_ALLOW_INSECURE=1 for localhost-only unauthenticated dev.

---

Security model

• Secrets in env only. Never committed, never passed as flags, never persisted. The self-hosted bearer token is cached in memory and re-fetched on 401.
• Never logged or echoed. A redaction layer scrubs secrets by key and by literal value from every log line, error, and tool result. get_me and user/admin responses are sanitized of token/authKey/shareToken. stdio diagnostics go to stderr only (stdout is the JSON-RPC channel).
• Remote endpoints are auth-gated and fail closed — constant-time bearer comparison; no MCP_AUTH_TOKEN ⇒ all requests rejected.
• Least privilege by default — read-only unless you opt in; destructive operations double-gated and annotated.
• No third-party credential collection. Run your own instance of this server. Never point credentials at someone else's hosted MCP endpoint.

See SECURITY.md for the full threat model and disclosure policy.

---

Tool reference

<details open> <summary><strong>Read tier (32 — always on)</strong></summary>

list_websites · get_website · get_website_daterange · get_active_visitors · get_realtime · get_stats · get_pageviews · get_metrics · get_website_values · get_events · get_event_data · list_sessions · get_session · get_session_activity · get_session_stats · get_session_properties · report_funnel · report_retention · report_journey · report_goals · report_attribution · report_revenue · report_utm · report_breakdown · list_reports · get_report · list_segments · get_segment · list_teams · get_team · get_team_members · get_me </details>

<details> <summary><strong>Write tier (UMAMI_ENABLE_WRITE)</strong></summary>

create_website · update_website · manage_website_share · transfer_website · send_event · create_team · update_team · join_team · add_team_member · update_team_member · create_segment · update_segment · create_report · update_report

Destructive (also needs UMAMI_ALLOW_DESTRUCTIVE): delete_website · reset_website · delete_team · remove_team_member · delete_segment · delete_report </details>

<details> <summary><strong>Admin tier (UMAMI_ENABLE_ADMIN — self-hosted)</strong></summary>

list_users · get_user · create_user · update_user · set_user_role

Destructive: delete_user </details>

Every tool returns a concise text summary plus a typed structuredContent payload, and accepts flexible date ranges (range: "7d" | "today" | "this-month", or explicit startAt/endAt).

---

Prompts & resources

Prompts (server-side, teach correct tool-chaining): analytics_report, traffic_overview, top_pages, acquisition_channels, realtime_check, funnel_analysis, retention_analysis, audience_insights, compare_periods.

Resources: umami://websites, umami://website/{id}, umami://me (sanitized).

---

Development

npm install
npm run build        # tsup → dist/{cli,http,server}.js
npm test             # vitest (58 tests)
npm run typecheck    # tsc --noEmit
npm run inspect      # MCP Inspector against the stdio CLI

Architecture: a single registerAll(server, ctx) core (src/server.ts) is shared by the stdio CLI (src/bin/cli.ts), the standalone HTTP server (src/http/server.ts), and the Vercel function (api/mcp.ts) — so the tool surface never drifts between local and hosted modes. See the design spec.

License

MIT © Mateusz Siatrak