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

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

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

list_users · get_user · create_user · update_user · set_user_role

Destructive: delete_user

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