Umami MCP Server

Read-only MCP server for Umami analytics. It talks to the Umami REST API directly over HTTP, supports self-hosted Umami first, and also works with Umami Cloud API keys.

This repo is built so upper-layer agents can ask for analytics without re-reading the Umami docs each time. No browser automation, no DOM scraping, no write operations.

Features

• Read-only MCP tools for the most common Umami analytics queries
• Two auth modes:
  • UMAMI_API_KEY
  • UMAMI_USERNAME + UMAMI_PASSWORD
• Self-hosted bearer token caching in memory
• Automatic re-login and one retry on 401 for username/password mode
• ISO time strings and millisecond timestamps both accepted
• Shared filter handling across stats, pageviews, breakdowns, and event series
• Strict TypeScript with small, maintainable modules
• Clear structured tool output and explicit error categories

Requirements

• Node.js >= 20
• pnpm >= 10

Install

From npm:

npm install -g umami-analytics-mcp

Or run without installing:

npx -y umami-analytics-mcp

For local development in this repo:

pnpm install

Configure

Create a .env file from .env.example.

cp .env.example .env

Fill in one of the following auth options:

1. API key mode

UMAMI_API_URL=https://api.umami.is/v1
UMAMI_API_KEY=your-api-key
UMAMI_DEFAULT_TIMEZONE=Asia/Shanghai

2. Self-hosted username/password mode

UMAMI_API_URL=https://umami.example.com/api
UMAMI_USERNAME=admin
UMAMI_PASSWORD=secret
UMAMI_DEFAULT_TIMEZONE=Asia/Shanghai

Notes:

• UMAMI_API_URL should point to the API base, not just the site origin.
• If both UMAMI_API_KEY and username/password are set, UMAMI_API_KEY wins.
• UMAMI_DEFAULT_TIMEZONE is used when a tool supports timezone and you omit it.

Run Locally

Development mode:

pnpm dev

Build and run:

pnpm build
pnpm start

The server uses MCP stdio transport, so it stays attached to stdin/stdout until the client disconnects.

If installed from npm, the equivalent command is:

umami-analytics-mcp

Test

pnpm test
pnpm build

There is also a real-API integration test template that is skipped by default:

UMAMI_INTEGRATION_TEST=1 pnpm test:integration

MCP Inspector

Build first:

pnpm build

Then launch the official MCP Inspector against the built server:

npx @modelcontextprotocol/inspector node dist/cli.js

For hot reload during development, this also works:

npx @modelcontextprotocol/inspector pnpm dev

If you want to test the published package path instead, use:

npx @modelcontextprotocol/inspector npx -y umami-analytics-mcp

Make sure the same Umami environment variables are available to the Inspector process.

Recommended smoke calls in Inspector:

1. umami_ping
2. umami_list_websites
3. umami_get_stats
4. umami_get_breakdown

Tools

umami_ping

Validates configuration and authentication.

Example:

{}

umami_list_websites

Lists accessible websites.

Example:

{}

umami_find_website

Fuzzy search by website name or domain.

Example:

{
  "query": "example.com"
}

umami_get_stats

Summary stats for a website and time range.

Example:

{
  "websiteId": "8f2f8ce2-1234-4567-89ab-0123456789ab",
  "startAt": "2026-04-23T00:00:00+08:00",
  "endAt": "2026-04-23T23:59:59+08:00",
  "filters": {
    "path": "/pricing"
  }
}

umami_get_pageviews

Time-series pageviews and sessions.

Example:

{
  "websiteId": "8f2f8ce2-1234-4567-89ab-0123456789ab",
  "startAt": "2026-04-17T00:00:00+08:00",
  "endAt": "2026-04-23T23:59:59+08:00",
  "unit": "day",
  "compare": "prev",
  "filters": {
    "path": "/blog"
  }
}

umami_get_breakdown

Breakdown rows such as top pages, referrers, countries, browsers, devices, and more.

Example:

{
  "websiteId": "8f2f8ce2-1234-4567-89ab-0123456789ab",
  "startAt": "2026-04-17T00:00:00+08:00",
  "endAt": "2026-04-23T23:59:59+08:00",
  "type": "path",
  "limit": 10,
  "expanded": false
}

umami_get_active

Returns the current active visitor count.

Example:

{
  "websiteId": "8f2f8ce2-1234-4567-89ab-0123456789ab"
}

umami_get_events_series

Returns custom event counts over time.

Example:

{
  "websiteId": "8f2f8ce2-1234-4567-89ab-0123456789ab",
  "startAt": "2026-04-17T00:00:00+08:00",
  "endAt": "2026-04-23T23:59:59+08:00",
  "unit": "day"
}

Shared Filters

These tools support the same filters object:

• path
• referrer
• title
• query
• browser
• os
• device
• country
• region
• city
• hostname

Error Handling

Tool errors are returned as structured MCP tool results with these categories:

• config_missing
• auth_failed
• website_not_found
• umami_http_error
• network_timeout
• network_error
• invalid_input

Mount In Any Stdio MCP Client

Any stdio-based MCP client can run this server with:

• command: npx
• args: ["-y", "umami-analytics-mcp"]
• env: your Umami variables

Example JSON snippet for clients that use an mcpServers object:

{
  "mcpServers": {
    "umami": {
      "command": "npx",
      "args": ["-y", "umami-analytics-mcp"],
      "env": {
        "UMAMI_API_URL": "https://umami.example.com/api",
        "UMAMI_USERNAME": "admin",
        "UMAMI_PASSWORD": "secret",
        "UMAMI_DEFAULT_TIMEZONE": "Asia/Shanghai"
      }
    }
  }
}

For a local unreleased checkout, you can still point directly to the built file:

{
  "mcpServers": {
    "umami": {
      "command": "node",
      "args": ["/absolute/path/to/umami-mcp/dist/cli.js"]
    }
  }
}

Publish To npm

This repo is now structured as an npm CLI package.

Recommended release flow:

pnpm test
pnpm build
pnpm pack --dry-run
npm login
pnpm publish

Notes:

• The package name is set to umami-analytics-mcp because umami-mcp is already taken on npm.
• The current license is UNLICENSED as a safe placeholder. Replace it before a real public open-source release if you want a permissive license.
• If you later publish under your own npm scope, change only the name field in package.json.

Internal Docs

• API summary used by this repo: docs/umami-api.md