# @umami/mcp [Model Context Protocol](https://modelcontextprotocol.io) server for [Umami](https://umami.is) 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: ```text Authorization: Bearer api_ ``` 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: ```text https://your-umami.example.com/mcp ``` Set the authorization header using your key: ```text Authorization: Bearer umami_ ``` 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 ```json { "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`: ```json { "mcpServers": { "umami": { "command": "npx", "args": ["-y", "@umami/mcp"], "env": { "UMAMI_API_KEY": "api_" } } } } ``` ## 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 ```ts 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`.