Umami MCP

official

Connect your AI assistant to Umami and ask questions about your website analytics in plain language.

GitHub

38.8k

Try this MCPSponsored

What can you do with Umami MCP?

List accessible sites — Ask to see all websites you can access; call list_websites first to get a websiteId for other queries.
Get traffic summaries — Ask for pageviews, visitors, bounce rate, or duration via get_website_stats, including comparisons to the previous period.
Analyze traffic sources — Ask which pages, referrers, countries, or devices drove traffic using get_website_metrics.
Track custom events — Ask about event totals, series, or property values with get_event_stats, get_event_series, or get_event_properties.
Inspect sessions — Ask for paginated session lists via get_sessions or a single session's activity timeline with get_session.
Run analytics models — Ask to execute saved funnels (run_funnel), view cohort retention (run_retention), or check goal conversions (get_goals).

Hosted MCP Server

npx add-mcp 'https://cloud.umami.is/mcp'

Installs into Claude Code, Codex, Cursor, VS Code and more

Documentation

@umami/mcp

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_daterange`	Earliest and latest dates with recorded data.
`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_event_stats`	Custom event totals + previous period.
`get_event_series`	Custom event counts over time, grouped by event name.
`get_event_properties`	Custom event property names, or the values of one property.
`get_sessions`	Visitor sessions (paginated).
`get_session_stats`	Session-level totals: visitors, visits, pageviews, events, countries.
`get_annotations`	Dated notes on the timeline (launches, campaigns) to explain changes.
`list_segments`	Saved segments and cohorts; pass IDs via `filters.segment` / `.cohort`.
`get_session`	One session with its activity timeline and properties.
`list_funnels`	Saved funnels with their steps (get a `funnelId` for `run_funnel`).
`run_funnel`	Conversion funnel from a saved `funnelId` or ad-hoc page/event steps.
`get_goals`	Saved goals with conversions, visitors and rate for a range.
`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.
`get_performance`	Core Web Vitals (LCP, INP, CLS, FCP, TTFB) percentiles, trend, breakdown.

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

Remote: Umami Cloud

Connect to https://cloud.umami.is/mcp using your existing Cloud API key:

Authorization: Bearer api_<your-cloud-api-key>

Clients that support custom headers may use x-umami-api-key instead. If both headers are provided, they must contain the same key. Use a client that supports API-key or bearer-header configuration.

Cloud MCP has the same subscription requirements and website/team permissions as the Cloud API. All tools call the Cloud API gateway, which validates the key and routes requests to your region.

Remote: self-hosted

Generate an API key under Settings → API keys in your Umami instance, then configure your MCP client with the Streamable HTTP endpoint:

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

Set the authorization header using your key:

Authorization: Bearer umami_<your-api-key>

Use a client that supports bearer tokens or custom authorization headers. The endpoint accepts self-hosted API keys; browser login tokens are not supported. Tools are read-only and respect the key owner's existing user/team permissions. Revoke the key in Settings to disconnect access. MCP is disabled by default. Set MCP_ENABLED=1 to enable the endpoint.

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.

For Cloud stdio, set UMAMI_API_KEY and omit UMAMI_URL and UMAMI_API_TOKEN:

{
  "mcpServers": {
    "umami": {
      "command": "npx",
      "args": ["-y", "@umami/mcp"],
      "env": { "UMAMI_API_KEY": "api_<your-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.
Which pricing plans did people select in the checkout event last month?
How many signup events fired each day this week?
Run my checkout funnel for last month.
How are we doing against our goals this quarter?
Which pages have the worst LCP on mobile?
What happened on the day traffic spiked?

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.