Model Context Protocol server for Umami analytics. Lets Claude, ChatGPT, Cursor and other MCP clients answer questions about your website traffic using read-only tools that call the Umami API through @umami/api-client.

The MCP server never talks to a database; every tool goes through the public API and the same user/team permission checks as the web app.

Tools

Tool	Purpose
`list_websites`	Find the websites you can access (call first to get a `websiteId`).
`get_website_stats`	Pageviews, visitors, visits, bounce rate, duration + previous period.
`get_website_traffic`	Pageview/visit time series by minute, hour, day, month or year.
`get_website_metrics`	Top pages, referrers, channels, countries, browsers, devices, UTM, events.
`get_realtime`	Visitors active right now.
`get_events`	Individual tracked events (paginated).
`get_sessions`	Visitor sessions (paginated).
`get_session`	One session with its activity timeline and properties.
`run_funnel`	Conversion funnel across page/event steps.
`run_journey`	Most common paths visitors take.
`run_retention`	Cohort retention table.
`run_attribution`	First/last-click attribution for a conversion.
`get_revenue`	Revenue totals, series and breakdowns.

All tools are read-only. Dates are ISO 8601; results are paginated with a hard cap on page size.

Remote (Umami Cloud / self-hosted with OAuth)

Add the MCP endpoint to your client:

https://cloud.umami.is/mcp
https://your-umami.example.com/mcp

The client discovers /.well-known/oauth-protected-resource/mcp, sends you to Umami to sign in and approve access (websites:read, analytics:read), and receives an OAuth token. No API key is pasted anywhere. Clients register via Client ID Metadata Documents; dynamic client registration is available for compatibility (OAUTH_DISABLE_DCR=1 turns it off).

Self-hosted instances can alternatively pass an API key (umami_…) as the bearer token.

Local / stdio

{
  "mcpServers": {
    "umami": {
      "command": "npx",
      "args": ["-y", "@umami/mcp"],
      "env": {
        "UMAMI_URL": "https://analytics.example.com",
        "UMAMI_API_TOKEN": "umami_…"
      }
    }
  }
}

Variable	Description
`UMAMI_URL`	Self-hosted instance URL (`/api` is appended).
`UMAMI_API_URL`	Full API base URL instead, e.g. `https://api.umami.is/v1`.
`UMAMI_API_TOKEN`	API key or login token (self-hosted).
`UMAMI_API_KEY`	Umami Cloud API key.

Example prompts

Show my websites.
How many visitors did example.com get last week?
What were the top 10 pages this month?
Compare traffic this month with the previous month.
Where is traffic coming from?
What signup events occurred yesterday?
Show sessions for user abc123.

Programmatic use

import { UmamiClient } from '@umami/api-client';
import { createUmamiMcpServer } from '@umami/mcp';

const server = createUmamiMcpServer({
  client: new UmamiClient({ baseUrl, token }),
});

createUmamiMcpHttpHandler({ createClient }) returns a Streamable HTTP handler for embedding in any web framework; the host verifies the bearer token and passes authInfo.