Umami MCP

A small, read-only Model Context Protocol server for self-hosted Umami 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:

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

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

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:

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:

[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:

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:

[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:

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

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

You can instead provide an existing bearer token:

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:

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.

Local development

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

Build and run the stdio server:

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:

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:

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