umami-mcp-server

MCP server for Umami Analytics — Cloud and self-hosted.

Exposes 11 read-only tools and 4 prompt templates over MCP. Built on the official TypeScript SDK. Runs with npx — no install required.

Quick start

npx umami-mcp-server

Or install globally:

npm install -g umami-mcp-server

Setup

Claude Code

claude mcp add -e UMAMI_API_KEY=your-api-key umami -- npx -y umami-mcp-server

Or add to .mcp.json in your project root:

{
  "mcpServers": {
    "umami": {
      "command": "npx",
      "args": ["-y", "umami-mcp-server"],
      "env": {
        "UMAMI_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Desktop

Settings > Developer > Edit Config > claude_desktop_config.json:

{
  "mcpServers": {
    "umami": {
      "command": "npx",
      "args": ["-y", "umami-mcp-server"],
      "env": {
        "UMAMI_API_KEY": "your-api-key"
      }
    }
  }
}

Cursor

.cursor/mcp.json:

{
  "mcpServers": {
    "umami": {
      "command": "npx",
      "args": ["-y", "umami-mcp-server"],
      "env": {
        "UMAMI_API_KEY": "your-api-key"
      }
    }
  }
}

VS Code (Copilot)

settings.json:

{
  "mcp": {
    "servers": {
      "umami": {
        "command": "npx",
        "args": ["-y", "umami-mcp-server"],
        "env": {
          "UMAMI_API_KEY": "your-api-key"
        }
      }
    }
  }
}

OpenAI Codex / Windsurf / Zed

Same pattern — command npx, args ["-y", "umami-mcp-server"], plus environment variables.

Self-hosted Umami

Replace the env block in any config above:

{
  "UMAMI_URL": "https://your-umami-instance.com",
  "UMAMI_USERNAME": "admin",
  "UMAMI_PASSWORD": "your-password"
}

Environment variables

| Variable | Required | Description | |----------|----------|-------------| | UMAMI_API_KEY | Cloud | API key from Umami Cloud Settings > API Keys | | UMAMI_API_BASE | No | API base URL (default: https://api.umami.is/v1) | | UMAMI_URL | Self-hosted | Umami instance URL | | UMAMI_USERNAME | Self-hosted | Login username | | UMAMI_PASSWORD | Self-hosted | Login password |

Set UMAMI_API_KEY for Cloud, or UMAMI_URL + UMAMI_USERNAME + UMAMI_PASSWORD for self-hosted. Auto-detected.

Tools

| Tool | Description | |------|-------------| | get_websites | List all tracked websites with IDs and creation dates | | get_stats | Aggregated stats: pageviews, visitors, visits, bounces, total time | | get_pageviews | Time-series pageview and session data by time unit | | get_metrics | Breakdown by path, referrer, browser, OS, device, country, city, language, screen, event, UTM params, and more | | get_active | Current active visitors in real-time | | get_daterange | Available data date range for a website | | get_events_series | Event data over time with timezone support | | get_metrics_expanded | Per-item stats: pageviews, unique visitors, visits, bounces, time on page | | get_sessions | Individual session details (paginated) | | get_sessions_stats | Session aggregates: pageviews, visitors, countries, events | | get_sessions_weekly | Heatmap: 7 days x 24 hours of session activity |

All tools are read-only.

Prompts

| Prompt | Description | Default | |--------|-------------|---------| | analytics-report | Full analytics report | 30 days | | top-pages | Most visited pages | 7 days, top 10 | | visitor-insights | Visitors by country, device, browser, OS | 30 days | | realtime-check | Current active visitors | — |

Example queries

• "What are my top 20 pages this month?"
• "Show me visitor trends for the last 90 days"
• "Which countries are my visitors from?"
• "How many people are on my site right now?"
• "What day and hour do I get the most traffic?"
• "Which pages have the highest bounce rate?"

How it works

Implements MCP over stdio (JSON-RPC 2.0). Handles initialize, tools/list, tools/call, prompts/list, prompts/get. Makes authenticated requests to the Umami API and returns structured JSON.

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

Requirements

• Node.js >= 18
• Umami Cloud account or self-hosted instance

License

MIT