# Umami MCP

[![CI](https://github.com/upnorthmedia/umami-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/upnorthmedia/umami-mcp/actions/workflows/ci.yml)

A small, read-only [Model Context Protocol](https://modelcontextprotocol.io/) server for self-hosted [Umami](https://umami.is/) analytics.

Use the hosted Streamable HTTP endpoint with credentials kept in your local environment, or run the server locally over stdio. Give it your Umami URL and either username/password credentials or a bearer token; it handles login and exposes a focused analytics toolset.

## Hosted quick start

The public endpoint is:

```text
https://umami-mcp-production-6324.up.railway.app/mcp
```

Set these variables in the environment that launches Codex or Claude Code:

```text
UMAMI_URL=https://analytics.example.com
UMAMI_USERNAME=admin
UMAMI_PASSWORD=your-password
```

### Claude Code

Run once to install the hosted MCP for your user:

```bash
claude mcp add-json --scope user umami '{"type":"http","url":"https://umami-mcp-production-6324.up.railway.app/mcp","headers":{"X-Umami-URL":"${UMAMI_URL}","X-Umami-Username":"${UMAMI_USERNAME}","X-Umami-Password":"${UMAMI_PASSWORD}"}}'
```

Run `claude mcp get umami` to inspect the configuration, then `/mcp` inside Claude Code to verify the connection.

### Codex

Add this to `~/.codex/config.toml`:

```toml
[mcp_servers.umami]
url = "https://umami-mcp-production-6324.up.railway.app/mcp"

[mcp_servers.umami.env_http_headers]
X-Umami-URL = "UMAMI_URL"
X-Umami-Username = "UMAMI_USERNAME"
X-Umami-Password = "UMAMI_PASSWORD"
```

Restart Codex, then use `/mcp` or `codex mcp list` to verify the server.

The environment variable names are stored in the client configuration; their values are added to HTTPS request headers at runtime. The hosted service uses the credentials for that request and does not persist them. It necessarily receives them in memory, so use the local stdio option if you do not want credentials to transit infrastructure operated by Up North Media.

### Use an existing Umami token

Replace the username and password headers with one token header:

```text
X-Umami-Token: your-bearer-token
```

For Claude Code, set `"X-Umami-Token":"${UMAMI_TOKEN}"`. For Codex, set `X-Umami-Token = "UMAMI_TOKEN"` under `env_http_headers`.

## Requirements

- Node.js 20 or newer
- An official self-hosted Umami v2 or v3 instance
- An Umami user with access to the websites you want to query

The shared v2/v3 read endpoints are supported. Umami forks or older releases may change their API contract; API errors are returned clearly instead of being hidden.

## Local stdio setup

### Codex

Add this to `~/.codex/config.toml`:

```toml
[mcp_servers.umami]
command = "npx"
args = ["-y", "github:upnorthmedia/umami-mcp"]

[mcp_servers.umami.env]
UMAMI_URL = "https://analytics.example.com"
UMAMI_USERNAME = "admin"
UMAMI_PASSWORD = "your-password"
```

Restart Codex, then use `/mcp` or `codex mcp list` to verify the server.

### Claude Code and other stdio clients

Use the equivalent MCP server configuration:

```json
{
  "mcpServers": {
    "umami": {
      "command": "npx",
      "args": ["-y", "github:upnorthmedia/umami-mcp"],
      "env": {
        "UMAMI_URL": "https://analytics.example.com",
        "UMAMI_USERNAME": "admin",
        "UMAMI_PASSWORD": "your-password"
      }
    }
  }
}
```

The exact settings-file location varies by MCP client. For Claude Code, this configuration can be stored in `.mcp.json` or added with `claude mcp add-json`.

## Authentication

Credential authentication is recommended because the server can log in again when an Umami session token expires:

```text
UMAMI_URL=https://analytics.example.com
UMAMI_USERNAME=admin
UMAMI_PASSWORD=your-password
```

You can instead provide an existing bearer token:

```text
UMAMI_URL=https://analytics.example.com
UMAMI_TOKEN=your-bearer-token
```

Choose one authentication method. The server rejects partial credentials or a token combined with username/password credentials.

`UMAMI_URL` can be the instance root, a base-path installation, or the API URL itself:

```text
https://analytics.example.com
https://example.com/analytics
https://analytics.example.com/api
```

## Tools

| Tool | Purpose |
| --- | --- |
| `list_websites` | List websites available to the authenticated user |
| `get_website` | Get one website's details |
| `get_active_visitors` | Get visitors active in the last five minutes |
| `get_stats` | Get summary pageviews, visitors, visits, bounces, and time |
| `get_pageviews` | Get pageview and session time series |
| `get_metrics` | Break down traffic by path, referrer, browser, device, country, event, or another supported metric |
| `get_events` | List pageview and custom-event details |
| `get_sessions` | List visitor sessions |
| `get_realtime` | Get activity from the last 30 minutes |

Every tool is marked read-only and non-destructive in its MCP annotations.

Date inputs accept either Unix timestamps in milliseconds or ISO 8601 date-times. Filters are passed through to Umami so the server can support version-specific fields. For example, Umami v3 calls its page filter `path`, while older v2 installations may use `url`.

`get_metrics` takes a `type` drawn from the columns both release lines accept. Two of those were renamed between the lines: a page is `path` on v3 and `url` on v2, and a host is `hostname` on v3 and `host` on v2. `domain`, `fullPath`, `distinctId`, `channel`, and the UTM breakdowns are v3 only. Umami rejects a column its version does not know with a bare `400` carrying no field information, so sending the other line's name comes back as an error naming the one to retry with.

## Local development

```bash
git clone https://github.com/upnorthmedia/umami-mcp.git
cd umami-mcp
npm install
npm run check
```

Build and run the stdio server:

```bash
npm run build
UMAMI_URL=https://analytics.example.com \
UMAMI_USERNAME=admin \
UMAMI_PASSWORD=your-password \
node dist/index.js
```

Tests use a real local HTTP server and the MCP SDK's linked in-memory transports. They do not contact your Umami instance.

Run the hosted transport locally:

```bash
npm run build
PORT=3000 npm start
```

Its MCP endpoint is `http://localhost:3000/mcp` and its health endpoint is `http://localhost:3000/health`. The hosted request mode still requires the target Umami instance to use HTTPS and a publicly routable address.

## Railway deployment

The included `Dockerfile` and `railway.toml` are production-ready:

```bash
railway init
railway add --service umami-mcp
railway up
railway domain --port 3000
```

No Umami credentials belong in Railway variables. Each MCP client sends its own locally configured credentials with its requests.

## Security

- Local stdio credentials are read from environment variables and are never returned by tools.
- Hosted credentials arrive in request headers populated by the user's local MCP client and are never logged or persisted by the service.
- The public HTTP service is stateless per MCP request and does not persist Umami credentials or session tokens.
- Hosted targets must use HTTPS, resolve only to public network addresses, contain no embedded URL credentials, and may not redirect.
- Browser-originated requests are rejected, and MCP requests are rate limited per client address.
- The server exposes analytics reads only; it has no create, update, delete, or reset tools.
- API errors include the status and Umami's error message without dumping request headers or credentials.

## License

[MIT](LICENSE)