Umami MCP Server

An MCP server for Umami Analytics — works with both Umami Cloud and self-hosted instances.

Zero dependencies. No cloning, no install steps — just point your MCP client at it.

Why?

Existing Umami MCP servers either don't support Umami Cloud (which uses API key auth, not username/password) or are broken and bloated (torch, faiss, sentence-transformers for… analytics?).

This server talks to the Umami API and exposes 5 tools over MCP. Pure Python, zero dependencies.

Tools

Tool	Description
get_websites	List all tracked websites
get_stats	Summary stats: pageviews, visitors, visits, bounces, totaltime (seconds)
get_pageviews	Time-series pageview/session data (unit: minute/hour/day/month/year; timezone: IANA, e.g. UTC)
get_metrics	Breakdown by type: path/url/entry/exit/referrer/domain/title/query/event/tag/hostname/browser/os/device/screen/language/country/region/city/channel
get_active	Number of currently active visitors (last 5 minutes)

Quick Start

1. Get your credentials

Umami Cloud: Go to Settings → API Keys in your Umami Cloud dashboard and create an API key.

Self-hosted: Use the username and password you log in with.

2. Add to your MCP client

No cloning required — uvx fetches and runs it directly from GitHub.

Requires uv. Install with: curl -LsSf https://astral.sh/uv/install.sh | sh

Claude Desktop / Claude Code

Add to your MCP config (~/.claude.json, Claude Desktop settings, etc.):

Umami Cloud:

{
  "mcpServers": {
    "umami": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/lukasschmit/umami-mcp", "umami-mcp"],
      "env": {
        "UMAMI_URL": "https://api.umami.is",
        "UMAMI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Self-hosted:

{
  "mcpServers": {
    "umami": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/lukasschmit/umami-mcp", "umami-mcp"],
      "env": {
        "UMAMI_URL": "https://your-umami-instance.com",
        "UMAMI_USERNAME": "admin",
        "UMAMI_PASSWORD": "your_password"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root (or global settings):

{
  "mcpServers": {
    "umami": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/lukasschmit/umami-mcp", "umami-mcp"],
      "env": {
        "UMAMI_URL": "https://api.umami.is",
        "UMAMI_API_KEY": "your_api_key_here"
      }
    }
  }
}

VS Code (Copilot)

Add to your VS Code settings.json:

{
  "mcp": {
    "servers": {
      "umami": {
        "command": "uvx",
        "args": ["--from", "git+https://github.com/lukasschmit/umami-mcp", "umami-mcp"],
        "env": {
          "UMAMI_URL": "https://api.umami.is",
          "UMAMI_API_KEY": "your_api_key_here"
        }
      }
    }
  }
}

BoltAI

Go to Settings → MCP Servers → Add Server, then enter:

• Command: uvx
• Arguments: --from git+https://github.com/lukasschmit/umami-mcp umami-mcp
• Environment Variables:
  • UMAMI_URL = https://api.umami.is
  • UMAMI_API_KEY = your_api_key_here

Environment Variables

Variable	Required	Description
UMAMI_URL	Self-hosted: Yes, Cloud: Optional	Base URL — defaults to https://api.umami.is in Cloud mode
UMAMI_API_KEY	Cloud	API key from Umami Cloud dashboard
UMAMI_USERNAME	Self-hosted	Login username
UMAMI_PASSWORD	Self-hosted	Login password
UMAMI_CF_ACCESS_CLIENT_ID	Optional	Cloudflare Access service token client ID (for protected self-hosted APIs)
UMAMI_CF_ACCESS_CLIENT_SECRET	Optional	Cloudflare Access service token secret
UMAMI_USER_AGENT	Optional	Custom User-Agent for outbound requests (default: umami-mcp/1.0)
UMAMI_DEBUG	Optional	Set to 1/true to log outbound request URLs to stderr for debugging

Set either UMAMI_API_KEY (Cloud) or both UMAMI_USERNAME + UMAMI_PASSWORD (self-hosted). The server auto-detects which mode to use. For convenience, UMAMI_URL may include /v1 (Cloud) or /api (self-hosted); suffixes are normalized automatically.

If your self-hosted Umami is behind Cloudflare Access, set both UMAMI_CF_ACCESS_CLIENT_ID and UMAMI_CF_ACCESS_CLIENT_SECRET so machine-to-machine MCP calls can pass Access checks.

get_metrics accepts both type="path" and type="url" for compatibility across Umami versions. startAt and endAt accept Unix-millisecond integers or numeric strings from MCP clients. For time-based tools, you can use range instead of raw timestamps: last_24h, last_7d, last_30d, this_month, last_month. compare supports prev (previous period, same length) and yoy (year-over-year).

Usage Examples

Once connected, you can ask your AI assistant things like:

• "What are my top pages this week?"
• "Show me visitor trends for the last 30 days"
• "Which countries are my visitors from?"
• "How many people are on my site right now?"
• "Compare this month's traffic to last month"

The assistant will call the appropriate tools with the right parameters.

How It Works

The server implements the Model Context Protocol over stdio (JSON-RPC, one JSON object per line). When an MCP client starts it, the server:

1. Reads JSON-RPC messages from stdin
2. Handles initialize, tools/list, and tools/call methods
3. Makes authenticated HTTP requests to the Umami API
4. Returns results as JSON text content

No background processes, no polling, no state beyond the auth token.

License

MIT