Umami MCP

What umami-mcp MCP server does

The umami-mcp MCP server connects an MCP client to an Umami Analytics v3 installation. It can inspect website traffic, visitor sessions, events, acquisition data, conversion reports, and revenue data. It can also list websites and, when permissions allow, create or update websites, teams, and users.

Analytics tools cover headline totals such as pageviews, visitors, visits, bounces, and time on site. Other tools provide time-bucketed pageviews, ranked dimensions such as pages or referrers, active visitors, real-time activity, event totals, session details, and the ordered activity within a session.

Report tools support UTM breakdowns, funnels, retention cohorts, visitor journeys, goals, revenue, and first-click or last-click attribution. A tracking-snippet tool returns the HTML script tag for a selected website.

How it works

The server communicates with the Umami instance identified by UMAMI_URL and authenticates with an Umami account username and password. It is designed for Umami v3 API behavior, including the v3 report endpoints and parameter formats. The server contacts only the configured Umami host when self-hosted.

By default, the server runs in read mode. In that mode, analytics, reports, and website listing are available. write mode adds website and team creation or updates, while admin mode adds user management. Destructive tools are exposed only when UMAMI_MCP_ALLOW_DESTRUCTIVE=true is also configured. A website deletion requires a typed domain confirmation checked against the current website record.

Setup and configuration

The umami-mcp MCP server requires Node.js 20 or newer when run from source. Clone the repository, install dependencies, and build it with npm install && npm run build. Register the resulting dist/index.js with an MCP client, or run the supplied Docker Compose setup after creating a .env file.

Credentials can be placed in ~/.config/umami-mcp/env, protected with restrictive file permissions. The lookup order supports UMAMI_MCP_ENV_FILE, the XDG configuration location, and a working-directory .env file; real environment variables override values loaded from files. The repository documents Claude Code, Claude Desktop, Cursor, and VS Code connections. The hosted deployment is available at https://umami-mcp.asif.dev/mcp, but self-hosting is the documented default for keeping credentials and analytics traffic under your control.

Relevant configuration includes:

• UMAMI_URL: the Umami instance URL.
• UMAMI_USERNAME: the account used for authentication.
• UMAMI_PASSWORD: the account password.
• UMAMI_MCP_MODE: read, write, or admin permission mode.
• UMAMI_MCP_ALLOW_DESTRUCTIVE: enables destructive tools when set to true.
• UMAMI_MCP_OAUTH: enables OAuth for a self-hosted deployment intended for web clients.

Tools and capabilities

The umami-mcp MCP server exposes tools for these workflows:

• Discover websites and inspect their UUIDs, domains, owners, and creation dates.
• Create or update website records and retrieve tracking snippets.
• Query traffic totals, time-series pageviews, dimensions, active visitors, and real-time activity.
• Inspect sessions and follow a visitor’s pageview and event sequence.
• Analyze UTM parameters, funnels, retention, journeys, goals, revenue, and attribution.
• List, create, and delete users or create teams when the configured mode permits those operations.
• Verify connectivity, authentication, and the active permission mode with umami_whoami.

Limitations and notes

This server uses a real Umami account password for self-hosted installations because self-hosted Umami does not provide API keys. Credentials are loaded from the process environment or a local environment file, and the server warns when that file is readable by other users. Passwords, bearer tokens, and JWTs are scrubbed from responses and errors.

Plain HTTP connections to remote hosts are rejected at startup; HTTP is allowed for localhost development. The npm package is not yet published according to the supplied documentation, so source installation or Docker is required until publication. The server is read-only by default, and enabling write or administrative operations increases the consequences of granting the account access.