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

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

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