How do I install ObsidianCorps Umami Analytics?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does ObsidianCorps Umami Analytics need an API key?

The publisher lists these environment variables: UMAMI_API_KEY, UMAMI_BASE_URL, UMAMI_TOKEN, UMAMI_USERNAME, UMAMI_PASSWORD, UMAMI_TWO_FACTOR_SECRET, UMAMI_DEFAULT_WEBSITE_ID.

What transport does ObsidianCorps Umami Analytics use?

ObsidianCorps Umami Analytics runs locally over stdio.

When was ObsidianCorps Umami Analytics last checked?

Last checked 2026-11-09. Umami v3 MCP for Cloud or self-hosted analytics, with read-only, privacy-conscious defaults.

ObsidianCorps Umami Analytics MCP server

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

npx -y @obsidiancorps/[email protected]

Credentials from the publisher

UMAMI_API_KEY — Umami Cloud API key. Configure this or one self-hosted authentication mode.
UMAMI_BASE_URL — Base URL of a self-hosted Umami instance, for example https://analytics.example.com.
UMAMI_TOKEN — Pre-issued self-hosted Umami token. Use with UMAMI_BASE_URL instead of login credentials.
UMAMI_USERNAME — Self-hosted Umami username. Use with UMAMI_BASE_URL and UMAMI_PASSWORD.
UMAMI_PASSWORD — Self-hosted Umami password. Use with UMAMI_BASE_URL and UMAMI_USERNAME.
UMAMI_TWO_FACTOR_SECRET — Optional Base32 TOTP setup secret for automatic Umami 3.3+ two-factor login.
UMAMI_DEFAULT_WEBSITE_ID — Optional default website UUID used when a tool call does not select a website.

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1UMAMI_API_KEY=<secret> UMAMI_BASE_URL=<value> UMAMI_TOKEN=<secret> UMAMI_USERNAME=<value> UMAMI_PASSWORD=<secret> UMAMI_TWO_FACTOR_SECRET=<secret> UMAMI_DEFAULT_WEBSITE_ID=<value> claude mcp add io.github.obsidiancorps-umami-mcp -- npx -y @obsidiancorps/umami-mcp@0.1.2

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "io.github.obsidiancorps-umami-mcp": {4      "command": "npx",5      "args": [6        "-y",7        "@obsidiancorps/[email protected]"8      ],9      "env": {10        "UMAMI_API_KEY": "<secret>",11        "UMAMI_BASE_URL": "<value>",12        "UMAMI_TOKEN": "<secret>",13        "UMAMI_USERNAME": "<value>",14        "UMAMI_PASSWORD": "<secret>",15        "UMAMI_TWO_FACTOR_SECRET": "<secret>",16        "UMAMI_DEFAULT_WEBSITE_ID": "<value>"17      }18    }19  }20}

claude_desktop_config.json

Local · npmPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

ObsidianCorps 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.

Umami MCP answering three analytics questions

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:

Mode	Variables	API base
Umami Cloud	`UMAMI_API_KEY`	Defaults to `https://api.umami.is/v1`
Self-hosted token	`UMAMI_BASE_URL`, `UMAMI_TOKEN`	`/api` is added to a root URL
Self-hosted login	`UMAMI_BASE_URL`, `UMAMI_USERNAME`, `UMAMI_PASSWORD`	`/api` is added to a root URL
Self-hosted login+2FA	Login variables plus `UMAMI_TWO_FACTOR_SECRET`	`/api` is added to a root URL
One-off 2FA login	Login variables plus a current six-digit `UMAMI_TWO_FACTOR_CODE`	`/api` is added to a root URL

UMAMI_TWO_FACTOR_SECRET is the Base32 setup seed shown when enrolling an authenticator. The MCP generates a six-digit SHA-1 TOTP just-in-time and never logs or returns it. Because storing the password and TOTP seed together removes the separation between factors, use a dedicated least-privilege Umami account and protect its environment. A pre-issued UMAMI_TOKEN avoids retaining either credential.

UMAMI_TWO_FACTOR_CODE is only a one-off fallback; it expires quickly and is unsuitable for normal MCP startup. Configure only one two-factor variable.

Non-local plain HTTP Umami URLs are rejected. For an explicitly trusted private network only, set UMAMI_ALLOW_INSECURE_HTTP=true.

Tools

The default read-only set is:

Tool	Purpose
`umami_check_connection`	Verify auth and inspect the current account
`umami_list_websites`, `umami_get_website`	Discover and inspect sites
`umami_get_overview`, `umami_get_metrics`	Aggregate KPIs, series, and ranked dimensions
`umami_get_realtime`	Inspect the current 30-minute activity window
`umami_list_sessions`, `umami_inspect_session`	Browse sessions, activity, properties, and replay metadata
`umami_query_session_data`	Query session properties, pivots, stats, weekly traffic, and typed series
`umami_list_events`, `umami_query_event_data`	Browse events, comparison stats, series, properties, values, and pivots
`umami_get_revenue`	Fetch revenue stats, charts, dimensions, and sessions
`umami_list_replays`	List replays or retrieve a replay event stream
`umami_run_report`, `umami_list_reports`	Run or discover funnel, journey, goal, retention, attribution, UTM, revenue, performance, breakdown, and heatmap reports
`umami_list_segments`	Discover segments and cohorts
`umami_list_assets`	Discover boards, tracked links, and pixels

Resources expose umami://capabilities and the live umami://websites list. Reusable prompts cover analytics review, conversion review, and realtime triage.

Time ranges

Most analytical tools accept either:

period: last_24_hours, last_7_days, last_30_days, last_90_days, today, yesterday, this_week, last_week, this_month, or last_month; or
both startAt and endAt as epoch milliseconds or ISO 8601 timestamps with an offset.

Calendar periods honor the supplied IANA timezone. Rolling periods retain the most recent data instead of rounding to midnight.

Mutations and destructive operations

No mutation tool is registered by default.

UMAMI_ENABLE_WRITE_TOOLS=true

This adds tools for creating/updating websites, segments, reports, boards/links/pixels, and sending analytics events. To additionally expose permanent reset/delete operations:

UMAMI_ENABLE_WRITE_TOOLS=true
UMAMI_ENABLE_DESTRUCTIVE_TOOLS=true

Destructive calls require confirmation strings such as RESET <website-id> or DELETE reports <report-id>. MCP annotations also identify these tools as destructive so supporting hosts can require approval.

Streamable HTTP

Loopback example:

MCP_TRANSPORT=http MCP_BEARER_TOKEN=replace-me npm start
# MCP:    http://127.0.0.1:3000/mcp
# Health: http://127.0.0.1:3000/health

For a container or non-loopback bind, both MCP_BEARER_TOKEN and MCP_ALLOWED_HOSTS are required:

docker build -t umami-mcp .
docker run --rm -p 3000:3000 \
  -e UMAMI_API_KEY=your-key \
  -e MCP_BEARER_TOKEN=long-random-secret \
  -e MCP_ALLOWED_HOSTS=mcp.example.com \
  umami-mcp

Set MCP_ALLOWED_ORIGINS to a comma-separated list of exact browser origins if browser-based MCP clients connect. Requests without an Origin header remain valid for native clients. Terminate TLS at a trusted reverse proxy; the built-in static bearer gate is suitable behind that boundary, not a replacement for OAuth on a public multi-user service.

Configuration reference

Variable	Default	Description
`UMAMI_BASE_URL`	Cloud API for API-key auth	Umami root or full API base URL
`UMAMI_DEFAULT_WEBSITE_ID`	—	Avoids site resolution for most calls
`UMAMI_TIMEOUT_MS`	`15000`	Upstream request timeout, 100–120000 ms
`UMAMI_MAX_RESPONSE_BYTES`	`512000`	Maximum upstream response, 1 KB–10 MB
`UMAMI_ENABLE_WRITE_TOOLS`	`false`	Registers non-destructive mutation tools
`UMAMI_ENABLE_DESTRUCTIVE_TOOLS`	`false`	Registers reset/delete tools; requires write tools
`MCP_TRANSPORT`	`stdio`	`stdio`, `http`, or `streamable-http`
`MCP_HOST`	`127.0.0.1`	HTTP bind address
`MCP_PORT`	`3000`	HTTP port
`MCP_BEARER_TOKEN`	—	Protects the HTTP MCP endpoint
`MCP_ALLOWED_HOSTS`	—	Comma-separated hostnames for non-loopback HTTP
`MCP_ALLOWED_ORIGINS`	—	Comma-separated exact browser origins

Development

npm install
npm test
npm run typecheck
npm run lint
npm run format:check
npm run build
npm run check

Tests drive the server through real in-memory, stdio, and Streamable HTTP MCP clients. See CONTRIBUTING.md and SECURITY.md before opening a change.

Compatibility baseline

Umami: v3.3.1, with compatibility expected for late v3 releases exposing the documented routes.
MCP SDK: TypeScript SDK v2.0.0.
MCP protocol: 2026-07-28 plus the SDK's stateless compatibility path for 2025-era clients.
Node.js: 20, 22, and 24.

Umami is a trademark of its respective owner. This independent integration is not affiliated with or endorsed by Umami Software.

License

Apache-2.0. See LICENSE.

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install ObsidianCorps Umami Analytics?

Does ObsidianCorps Umami Analytics need an API key?

What transport does ObsidianCorps Umami Analytics use?

When was ObsidianCorps Umami Analytics last checked?

Documentation

ObsidianCorps Umami MCP

Install

Agent skill

Why this implementation

Configure

From source

Authentication

Tools

Time ranges

Mutations and destructive operations

Streamable HTTP

Configuration reference

Development

Compatibility baseline

License