# Umami MCP Server

An MCP server for [Umami Analytics](https://umami.is) — 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](https://github.com/Macawls/umami-mcp-server) (which uses API key auth, not username/password) or are [broken and bloated](https://github.com/jakeyShakey/umami_mcp_server) (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](https://cloud.umami.is) 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`](https://docs.astral.sh/uv/getting-started/installation/).** 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:**
```json
{
  "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:**
```json
{
  "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):

```json
{
  "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`:

```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](https://modelcontextprotocol.io/) 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