umami-mcp-server
An MCP server for Umami Analytics (Cloud or self-hosted) that lets an agent query web analytics in plain ranges and site names, and manage Umami resources — including destructive writes — with confirm=true gating.
Discover sites: list websites (with search), get one website's config, collected-data date range, and live visitor count.
Core traffic analytics: summary stats (pageviews, visitors, visits, bounce rate, avg visit duration) with period-over-period comparison; pageview/session time series with auto bucket sizing; custom event counts over time; ranked breakdowns by ~25 dimensions (path, entry/exit, referrer, channel, country, device, browser, event, UTM, etc.) with filters and
expanded=trueengagement metrics.One-call report:
umami_traffic_reportreturns stats plus seven breakdowns, dropping unsupported dimensions instead of failing.Sessions: paginated session lists and single-session detail with the full page/event activity trail.
Derived behavior analytics: goal conversion rate, ordered funnels (2–8 steps, session-trail walking), common page journeys, cohort retention (needs
umami.identify()), and revenue summed from a numeric event property.Replays & heatmaps: list recordings, summarize a replay (pages, clicks, optional raw click coordinates — never the raw rrweb stream), build a normalized click-density grid for a path, and read the live recorder config the tracker actually receives.
Persist dashboard objects: create/list/delete saved goals, funnels, journeys, retention reports, audience segments, and cohorts so they appear in the Umami UI.
Admin CRUD (self-hosted): create/update/delete websites (including full replay/heatmap config), users, teams, and team membership; join teams by access code; reset a website's data while keeping its tracking ID.
Onboarding composite:
umami_onboard_clientcreates a website, optional team, optional user grant, and replay settings in one best-effort call, returning the tracking snippet.Safety controls: every destructive/reset/remove tool requires a literal
confirm: true; write tools carryreadOnlyHint: false; credential scoping is the real ceiling.Escape hatch:
umami_api_getperforms read-only GETs against any Umami endpoint not covered by a dedicated tool.Consistent ergonomics: every data tool accepts
markdownorjsonoutput, flexible relative/named/explicit date ranges, IANA timezone, and a sharedfiltersobject; website arguments accept UUID, name, or domain.
Provides integration with Umami Analytics, enabling analytics queries (stats, pageviews, metrics, event series, sessions, traffic reports) and admin management of websites, users, and teams on self-hosted instances.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@umami-mcp-server show me traffic stats for example.com over the last 7 days"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
umami-mcp-server
An MCP server for Umami Analytics. Works against both Umami Cloud and self-hosted instances, and speaks in ranges like last_month and site names like example.com rather than epoch milliseconds and UUIDs.
Eighty-one tools covering website discovery, traffic stats, time series, ranked breakdowns, custom events, individual sessions, funnels, journeys, goals, retention, revenue, session replays and click heatmaps, saved reports and audience segments that show up in the Umami UI, dashboards (boards and the home dashboard) built from one-call templates, chart annotations, tracking links and pixels, an event-property explorer, server-side event sending, full admin CRUD for websites/users/teams, a composite client-onboarding tool, and a raw GET escape hatch for anything else in the Umami API.
This server is not read-only. Most tools read, but it can also create, update, and permanently delete websites, users, teams, saved reports, segments, dashboards, links, and pixels, it can write events into your real analytics, and it can wipe a website's collected data. See Write access and safety before connecting it to anything you care about.
Admin tools (creating users, teams, and websites; deleting anything) require self-hosted Umami with an admin login or admin API key. Umami Cloud does not expose user or team management via the API, so those tools return a clear error rather than a confusing 404 if pointed at Cloud.
What you can ask it
The Umami dashboard is a good place to look at your analytics. It is a tedious place to set them up, and a slow place to answer a question that needs three screens and a UUID. That is the gap this server fills: you describe what you want in plain language, and your agent picks the tool, resolves example.com to its ID, turns "last month" into timestamps in your timezone, and hands back a readable answer. Everything below is a real thing you can type.
See how the site is doing.
"How did example.com do last month compared to the month before?" →
umami_get_statswithrange=last_month"Give me the full rundown for the last 30 days" →
umami_traffic_report, stats plus seven breakdowns in one call"Which landing page has the worst bounce rate?" →
umami_get_metricswithtype=entry,expanded=true"Show me top pages for mobile visitors in Florida" →
umami_get_metricswithfilters={ device: "mobile", region: "US-FL" }"How many contact form submits this week?" →
umami_get_events_serieswithevent=contact-form-submit
Work out why. These are the questions a stats page cannot answer, and the ones this server computes for you even though Umami has no endpoint for them.
"Where do people drop off between pricing and signup?" →
umami_get_funnelwithsteps=["/pricing", "/signup", "signup-complete"]"What do people actually do after landing on the homepage?" →
umami_get_journeyswithstart_path="/""Where are people clicking on the pricing page?" →
umami_get_click_heatmapwithpath="/pricing""What did that one session do on the site?" →
umami_list_sessions, thenumami_get_sessionorumami_get_replay"How much revenue came from Google this month?" →
umami_get_revenuewithevent=purchase,property=amount,filters={ utmSource: "google" }"Do people come back the week after they sign up?" →
umami_get_retention, if the site callsumami.identify()
Set the dashboard up by talking to it. Answers computed on demand disappear when the conversation ends. Describe the goal, funnel, or segment you want and it is built for you in the Umami web UI, waiting there for anyone who logs in, without you filling in the forms.
"Save that funnel so the client sees it under Behavior" →
umami_create_funnel"Make a goal for the thank-you page" →
umami_create_goal"Create a segment for paid mobile traffic" →
umami_create_segment"What reports are already saved for this site?" →
umami_list_saved_reports
Build the dashboards. Umami 3 calls them Boards, plus one home dashboard per user. Build a finished one from a template, or lay widgets out yourself. See Dashboards and templates.
"Build a lead-gen dashboard for example.com" →
umami_build_templatewithtemplate=leadgen. It reuses the goals and funnels the site already has, creates only what is missing, and builds one board"Make a clean report board for the client" →
umami_build_templatewithtemplate=client_report"Put all my sites on the home dashboard, the three main ones in full" →
umami_set_dashboardwithwebsites=[...]andcompact_websites=[...]"Add a traffic chart and top referrers to that board" →
umami_update_board
Annotate, tag, and dig into events.
"Mark the day we launched the new homepage on the charts" →
umami_create_annotation"Make a tracking link for the spring email" →
umami_create_link, orumami_create_pixelfor email opens"What properties does the claim_click event carry, and what values?" →
umami_list_event_properties, thenumami_get_event_property_values"Which source gets credit for signups, first click or last?" →
umami_run_reportwithtype=attribution"Record this webhook as a purchase event" →
umami_send_eventwithconfirm=true
Run the instance. Self-hosted, with an admin credential.
"Set up tracking for the new client, its own team, and put jordan on it" →
umami_onboard_client, one call for website plus team plus access"Give me the tracking snippet for that site" → comes back with the
<script>tag fromumami_create_website"Turn on session recording at 25 percent sampling, and mask form inputs" →
umami_update_website, thenumami_get_recorder_configto confirm what the tracker actually receives"Wipe the test data before this site goes live" →
umami_reset_websitewithconfirm=true
A useful pattern is chaining without naming any tools: "which page loses the most people, then show me a few recordings of them leaving" walks umami_get_metrics, then umami_list_replays filtered to that path, then umami_get_replay. Three screens and some ID copying in the UI, one sentence here.
Related MCP server: @byterover/umami-mcp
Install
npm install
npm run buildConfigure
Copy .env.example and fill in one of the two auth paths.
Umami Cloud
Create a key under Settings, API keys.
Variable | Required | Notes |
| yes | Your Cloud API key |
| no |
|
Self-hosted
Variable | Required | Notes |
| yes | Root URL of the instance, e.g. |
| either | An API key on the instance |
| either | Login credentials, exchanged for a bearer token and refreshed automatically when it expires |
Both
Variable | Default | Notes |
|
| IANA timezone for day boundaries and time-series buckets, e.g. |
| none | Website ID, name, or domain used when a tool call omits |
Connect it
Claude Desktop or Claude Code
Add to claude_desktop_config.json, or run claude mcp add:
{
"mcpServers": {
"umami": {
"command": "node",
"args": ["/absolute/path/to/umami-mcp-server/dist/index.js"],
"env": {
"UMAMI_API_KEY": "your-key",
"UMAMI_TIMEZONE": "America/New_York",
"UMAMI_DEFAULT_WEBSITE": "example.com"
}
}
}
}For a self-hosted instance, swap in UMAMI_BASE_URL and either the key or the username and password pair.
MCP Inspector
UMAMI_API_KEY=your-key npm run inspectWrite access and safety
The credentials you give this server are the real ceiling on what it can do. An admin key means the agent holds admin rights.
Tools that change state:
Create:
umami_create_website,umami_create_user,umami_create_team,umami_create_goal,umami_create_funnel,umami_create_segment,umami_create_cohort,umami_create_board,umami_set_dashboard,umami_create_annotation,umami_create_link,umami_create_pixel,umami_create_share,umami_onboard_client,umami_build_template(creates goals, funnels, and a board; see below)Update:
umami_update_website,umami_update_user,umami_update_team,umami_update_team_user,umami_add_team_user,umami_join_team,umami_update_board,umami_update_annotation,umami_update_link,umami_update_pixelWrite into your real analytics:
umami_send_event,umami_send_identify. They requireconfirm=truebecause they add data that looks like real visitors. Test on a throwaway site.Delete or wipe:
umami_reset_website,umami_delete_website,umami_delete_user,umami_delete_team,umami_remove_team_user,umami_delete_saved_report,umami_delete_segment_cohort,umami_delete_board,umami_delete_annotation,umami_delete_link,umami_delete_pixel,umami_delete_share
Public exposure. umami_create_share and umami_build_template with public_share=true create a public, read-only URL that anyone holding it can open. umami_create_link and umami_update_link create or repoint a public redirect. All of these require confirm=true (or, for the template, an explicit public_share=true), so none can happen by default or as a side effect.
Every tool in the delete-or-wipe group requires a literal confirm: true argument and fails without it. There is no second round-trip: the tool call itself is the confirmation, and umami_reset_website and umami_delete_website destroy collected analytics data that cannot be recovered.
To run this read-only, scope the credential rather than trusting the tool list: give it a non-admin API key, or a login whose role only grants view access to the websites it should see. Umami enforces that server-side, so the write tools fail with a permission error instead of succeeding.
If your MCP client supports per-tool permissions, a second layer is to allowlist only the umami_get_*, umami_list_*, umami_traffic_report, and umami_api_get tools, and gate or deny the rest.
Tools
Analytics (read-only)
Tool | What it does |
| List every tracked website, with optional search. Start here when you do not know an ID |
| Website config plus the date range of data actually collected, plus the live visitor count |
| Unique visitors in the last 5 minutes |
| Pageviews, visitors, visits, bounce rate, average visit duration, with period-over-period change |
| Pageviews and sessions bucketed by minute, hour, day, month, or year |
| Ranked breakdown by any dimension. |
| Custom event counts over time, grouped by event name |
| Paginated list of individual anonymous sessions |
| One session plus its page-by-page activity trail |
| Stats and seven breakdowns in a single call. The right tool for "how is the site doing" |
Behavior analysis (read-only, computed here)
Umami has no endpoints for any of these. Each is derived from data Umami does expose, so they work on stock instances but cost more API calls than a plain stat. See Design notes for what that costs.
Tool | What it does |
| Conversion rate toward one page or one custom event, against the same-range visitor baseline. Two filtered stats calls |
| Session counts and drop-off across 2 to 8 ordered steps, each a page path or an event name. Walks session activity trails |
| The most common ordered page sequences visitors take, optionally from a given entry path |
| Cohort retention curve by day, week, or month. Requires the site to call |
| Total, average, and count from a numeric property on a custom event, e.g. an |
Session replay and heatmaps (read-only)
Tool | What it does |
| Recorded session replays for a range, newest first. Only exist where recording is enabled and the session was sampled |
| Summary of one replay: pages, click count, duration and event breakdown. Optionally the raw click coordinates. Never the raw rrweb stream |
| Click-density grid for one page path, built by downloading replays and normalizing every click against its recording's viewport |
| The live config Umami is actually serving to the tracker. Ground truth after |
Saved reports and audiences (visible in the Umami UI)
Everything above computes on demand and leaves no trace in the dashboard. These persist definitions so they appear in the Umami web UI for anyone browsing it.
Tool | What it does |
| Persist a Goal under Behavior, Goals |
| Persist a Funnel under Behavior, Funnels |
| List saved goals, funnels, journeys, or retention reports for a website |
| Destructive. Delete a saved report. Requires |
| Persist an audience Segment (a saved filter combination) under Audience, Segments |
| Persist a Cohort (visitors who did something in a window, optionally filtered further) under Audience, Cohorts |
| List saved segments or cohorts |
| Destructive. Delete a saved segment or cohort. Requires |
Admin: websites (self-hosted, admin login or key)
Tool | What it does |
| Register a new website and get back its tracking ID and |
| Rename, change domain, set a public share link, and configure every replay/heatmap field: enable flags, sample rates, PII mask level, max recording length, block selector |
| Destructive. Wipe all collected data, keep the website and tracking ID. Requires |
| Destructive. Delete the website registration and all its data. Requires |
Admin: users (self-hosted, admin login or key)
Tool | What it does |
| Create an internal login |
| List every login on the instance |
| One user's role plus the websites and teams they can access |
| Change username, password, or instance-wide role |
| Destructive. Remove a login. Requires |
Admin: teams (self-hosted, admin login or key)
Tool | What it does |
| Create a team and get its access code |
| List teams with member and website counts |
| Team details plus full member list and roles |
| Websites belonging to a team |
| Rename a team or rotate its access code |
| Join a team as the authenticated user, via access code |
| Add an existing login to a team directly |
| Change a team member's role |
| Destructive. Remove a member from a team. Requires |
| Destructive. Delete a team. Requires |
Dashboards and templates
Umami 3 has two kinds of dashboard. Boards are named dashboards, each for one website. The home dashboard is the single page Umami opens on login, one per user, and its widgets can come from several websites. Both are built from a grid: rows of up to 4 widgets.
Tool | What it does |
| One call builds a finished board from an opinionated template (below). Detects what the site tracks, reuses saved goals and funnels, creates only what is missing, and updates the board in place if it already exists. |
| List dashboards with the widget types in each |
| Create a board for one website from a |
| Rename a board, or replace its layout |
| Destructive. Delete a board. Requires |
| Read the home dashboard |
| Build the home dashboard, replacing its layout. |
Templates for umami_build_template:
Template | Builds | Notes |
| KPI bar, goal widgets, funnels, traffic chart, UTM source and campaign tables, channels, landing pages, top events and referrers | Reuses the site's saved goals and funnels. |
| KPI bar, live visitors, traffic chart, events bar and chart, event and page tables, devices, browsers, weekly traffic | Umami has no retention widget, so this uses realtime and events. Needs the site to send custom events to show anything beyond traffic |
| KPI bar, traffic chart, top pages and referrers, countries and devices, world map | Clean and shareable. |
Presets for umami_create_board: overview, acquisition, behavior, realtime, revenue. A preset is a fixed layout with no goal or funnel logic. A template is a preset plus the site-aware parts.
Widgets: WebsiteMetricsBar, WebsiteChart, MetricsTable, WorldMap, WeeklyTraffic, UTM, EventsMetricsBar, EventsChart, Goal, Funnel, RealtimeHeader, RealtimeChart, RealtimeActiveUsers, RevenueMetricsBar, RevenueChart, RevenueMetricsTable, TextBlock. Goal and Funnel need a report_id from umami_list_saved_reports. MetricsTable takes props.type (path, referrer, country, browser, os, device, event, entry, exit, channel, and more) and props.limit (5, 10, or 20).
Annotations, tracking links, pixels, and shares
Tool | What it does |
| Dated notes pinned to a website's charts ("launched new homepage"). Umami 3.4+ |
| Short tracking links that redirect to a URL and count clicks |
| 1x1 tracking pixels that count loads, for email opens and similar |
| Public read-only share links for a website, link, pixel, or board |
Public share links
A share link is a public URL, {your Umami}/share/{slug}, that opens a read-only view of one website, tracking link, pixel, or board. Nobody needs a login, and anyone who has the URL can see it, so treat it like publishing the numbers. Revoke one with umami_delete_share.
Two ways to create one, both explicit. Nothing in this server creates a share link as a side effect:
umami_create_sharewithtype(website,link,pixel, orboard), the entity, a name, andconfirm=true, meaning you intend to make that data public. Umami generates the slug unless you set oneumami_build_templatewithtemplate=client_reportandpublic_share=true, which builds the board and shares it in one step
Good for a read-only client report you can send as a link. Be careful with a board that shows a client's traffic you would not want their competitors to see.
Embedding it in another site (an iframe) does not work out of the box. Umami sends Content-Security-Policy: frame-ancestors 'self', so browsers refuse to show its pages inside any other site. This was checked against a self-hosted v3.4.1 instance. To allow it, set ALLOWED_FRAME_URLS on the Umami server to the site that will embed it (for example https://example.com) and redeploy. Umami Cloud does not expose that setting, so on Cloud use the link directly instead of an iframe. The share page also loads its data from your Umami, so the embedding page needs no credentials.
Event data explorer (read-only)
Tool | What it does |
| Every custom event and the property names recorded on it, with counts. Start here to see what an event carries |
| Distinct values and counts for one property of one event |
| Properties attached to visitors through |
| Distinct values and counts for one visitor property |
Revenue and reports (read-only)
Tool | What it does |
| Umami's native revenue summary with comparison to the previous period. Needs revenue tracking enabled |
| Native revenue over time |
| Native revenue by referrer, channel, country, or region |
| Compute a report type with no dedicated tool: |
umami_get_revenue (in Behavior analysis) sums a numeric property on a custom event. The native umami_get_revenue_* tools read Umami's own revenue reports. Use whichever matches how your site reports revenue.
Sending data in
Tool | What it does |
| Record a pageview or custom event, as if a visitor triggered it. For server-side events like webhooks. Writes into real stats. Requires |
| Attach properties to a visitor. Writes into real stats. Requires |
| The logged-in user's id, username, and role. Useful to confirm credentials work. Session tokens are stripped from the response |
Provisioning
Tool | What it does |
| One call: create a website, optionally a dedicated team for it, optionally grant an existing user access, optionally set replay/heatmap config from the start. The fast path for setting up a new client |
Escape hatch
Tool | What it does |
| Read-only GET against any Umami endpoint without a dedicated tool. Cannot create, modify, reset, or delete anything |
Every data tool takes response_format: markdown for a readable summary, json for the structured payload.
Date ranges
Pass range as any of:
Relative:
30m,24h,7d,4w,3mo,1yNamed:
today,yesterday,this_week,last_week,this_month,last_month,this_year,last_year,mtd,ytd,all_time
Or pass start_date and end_date as YYYY-MM-DD, a full ISO 8601 timestamp, or epoch milliseconds. Explicit dates override range. Day boundaries respect UMAMI_TIMEZONE, or a per-call timezone argument.
Filters
Most tools accept a filters object that segments the query:
{ "country": "US", "device": "mobile", "path": "/pricing" }Supported keys: path, referrer, title, query, browser, os, device, country, region, city, language, hostname, tag, event, distinctId, utmSource, utmMedium, utmCampaign, utmContent, utmTerm, segment, cohort.
Breakdown dimensions
For umami_get_metrics and the breakdowns argument of umami_traffic_report: path, entry, exit, title, query, referrer, channel, domain, country, region, city, browser, os, device, language, screen, event, hostname, tag, distinctId, plus the five utm* dimensions.
Design notes
Website resolution. Any tool's
websiteargument accepts a UUID, a name, or a domain. Names and domains are matched against a 60-second cached website list, with an explicit ambiguity error rather than a silent wrong guess. Creating, updating, or deleting a website refreshes that cache immediately.Undocumented endpoints, marked as such. Saved goals, funnels, journeys, and retention reports live on
POST/GET/DELETE /reports; segments and cohorts live on a separate/websites/:id/segments. Neither is in Umami's published REST API. Both were mapped by watching the web UI's own network calls, and the exact request shapes are documented in comments at the top ofsrc/tools/saved-reports.tsandsrc/tools/segments.ts, including which enum values a 400 response confirmed. These can change without notice on a future Umami version, unlike the documented analytics endpoints.Derived analytics cost API calls. Funnels and journeys have no endpoint, so both walk session activity trails: one
/sessionspage plus one/sessions/:id/activitycall per session, capped bymax_sessions(default 500, max 2000) and reported back astruncatedwhen the range held more. The click heatmap downloads up tomax_replaysrecordings (default 100). Umami Cloud rate-limits to 50 calls per 15 seconds, and the client surfaces that as a plain message rather than a raw 429. Raise the caps deliberately.Retention needs instrumentation, not just traffic.
umami_get_retentionis built fromdistinctId, which only exists where the site callsumami.identify(persistentId). Without it, cohort size is 0 no matter how much real traffic there is, and the tool says so instead of reporting a broken curve.Dashboards are undocumented too. Boards live on
/boardsand the home dashboard on/dashboard. Neither is in Umami's published API. The shapes (parameters.rows[].columns[].component, the widget type list, the 4-column editor limit and 300px minimum column width) come from Umami's source and a live 400 response, and are noted at the top ofsrc/tools/boards.ts.Templates read the site first.
umami_build_templatelooks at the site's saved goals and funnels and its top events from the last 90 days before building, so a template on a site with no conversion events produces a board with empty goal widgets, not an error. The board is named<site> <template>. Running it again updates the board with that name for that website instead of making a duplicate; a board with the same name on a different website is never touched. If the board being updated has public share links, the result says so.Event names are untrusted. Anyone who can reach a site's tracker can send an event with any name, so the template never creates a goal from a name it found in analytics. It suggests them (plain identifiers only, seen at least 3 times) and creates goals only from the
conversionslist you pass.A Umami quirk the tools work around.
POST /dashboardreturns a 500 unlessdescriptionis sent, because the column is NOT NULL but the request validation marks it optional.umami_set_dashboardalways sends an empty string.Sending events needs a browser-like user agent. Umami's collector silently drops requests from non-browser user agents and answers
{"beep":"boop"}.umami_send_eventsends a realistic one by default and reports the drop as an error if it still happens. Passuser_agentto override.Session tokens never reach the model. Umami's own
/meresponse includes the live bearer token.umami_get_mereturns only an allowlist of fields (id, username, role, isAdmin, createdAt). Separately, every tool's JSON output, including the rawumami_api_get, redacts any key namedtoken,authKey,shareToken,apiKey,password, orsecret, so reading/methrough the escape hatch is covered too.Visitor data is untrusted. Event names, property names, and property values come from public tracker traffic, so anyone can send anything. The event data explorer tools return them under a
noticesaying so, with every control, zero-width, bidirectional-override, tag, and line-separator character replaced by a space (after Unicode NFKC normalization) and each string capped at 100 characters, counted by code point. Treat them as data to report on, not as instructions, and keep that in mind before letting an agent with write tools act on them.umami_build_templateapplies the same rule when it looks for conversion events.Computed versus saved.
umami_get_goalandumami_get_funnelcompute on demand and leave nothing in the dashboard.umami_create_goalandumami_create_funnelpersist a definition that shows up in the Umami UI. Two different jobs, deliberately two different tools.Full replay/heatmap config, not just toggles.
umami_update_websiteexposes every field Umami'sreplayConfigaccepts: enable flags, independent sample rates for replay vs. heatmaps, PII mask level, block selector, and max recording duration. Umami's own docs give inconsistent units formaxDuration(one example implies milliseconds, another implies seconds); rather than guess,umami_get_recorder_configreads the same public endpoint the tracker itself calls, so you can confirm the effective value after saving instead of trusting either doc example.Replays are summarized, never dumped.
umami_get_replayreturns pages, click count, and a duration breakdown. The raw rrweb event stream can run to tens of thousands of events and would blow any context window.Derived metrics. Umami returns raw
bouncesandtotaltimecounts. Bounce rate, views per visit, and average visit duration are computed here so every response is directly readable.Partial failure.
umami_traffic_reportruns its breakdowns in parallel and drops any dimension the instance does not support, naming the skipped ones instead of failing the whole report. This matters because dimension support varies across Umami versions.Destructive ops are opt-in, not confirmed twice. Every reset, delete, and remove tool requires a literal
confirm: trueargument and fails otherwise. There is no separate "are you sure" round-trip: the tool call itself is the confirmation, so an agent (or a person) should only passconfirm: trueonce they mean it.umami_onboard_clientis best-effort, not transactional. Umami's API has no multi-step transaction support. If team creation succeeds but the website step fails, the team is left in place and the error message says so explicitly, along with what to check next, rather than silently rolling back or hiding the partial state.Escape hatch stays read-only.
umami_api_getis deliberately GET-only, separate from the admin tools above. It cannot create, modify, reset, or delete anything.Response size. Responses are capped at 25,000 characters with a message pointing at
limit,offset, or a narrower range.
Tests
npm testThree suites run against a fake Umami API over a real MCP stdio client. test/smoke.mjs exercises the analytics tools plus their error paths. test/auth.mjs covers the self-hosted login exchange and the token refresh that fires when a cached bearer token goes stale. test/admin.mjs covers website/user/team CRUD, team membership, the composite onboarding tool, and confirms every destructive admin tool refuses to run without confirm=true.
Coverage is the core analytics and admin surface. The behavior-analysis, replay, saved-report, segment, dashboard, template, annotation, link, pixel, share, event-data, revenue, report, and send tools are not yet in the suites. They have been verified by hand against a live self-hosted instance (Umami v3.4.1): the read-only calls, the home dashboard, boards, and the leadgen template were run end to end. The product and client_report templates have only been dry-run. The create, update, and delete calls for annotations, links, pixels, and shares, and the two umami_send_* tools, have not been exercised against a live instance yet.
Verified against
Umami v3 API as of November 2026, run against self-hosted Umami v3.4.1.
Documented endpoints: /websites, /websites/:id, /websites/:id/stats, /pageviews, /metrics, /metrics/expanded, /events/series, /active, /daterange, /sessions, /sessions/:id, /sessions/:id/activity, /websites/:id/reset, /websites/:id/event-data/values, /users, /admin/users, /users/:id, /users/:id/websites, /users/:id/teams, /teams, /teams/join, /teams/:id, /teams/:id/users, /teams/:id/users/:userId, /teams/:id/websites.
Undocumented endpoints, mapped from the web UI and Umami's source: /reports (saved goals, funnels, journeys, retention) and /reports/:type (attribution, breakdown, utm, performance), /websites/:id/segments (segments and cohorts), /websites/:id/replays, /websites/:id/replays/:id, /boards, /boards/:id, /dashboard, /links, /pixels, /share, /share/id/:id, /websites/:id/annotations, /websites/:id/shares, /websites/:id/revenue/{stats,chart,metrics}, /websites/:id/event-data/{events,values}, /websites/:id/session-data/{properties,values}, /send.
Cloud requests go to https://api.umami.is/v1 with a bearer token; self-hosted requests go to {base}/api. User and team management endpoints only exist on self-hosted instances.
License
MIT
Available Tools
48 toolsumami_add_team_userAdd a user to a teamA
Add an existing Umami login to a team directly, without needing the access code. Requires team-manager or owner permission on the team.
Args:
team_id (string, required): Team UUID.
user_id (string, required): User UUID to add. Get this from umami_list_users.
role ('team-manager' | 'team-member' | 'team-view-only'): Role within the team (default: 'team-member').
Returns: { "team_id": string, "user_id": string, "role": string }
Examples:
"Add jordan to the Gradeline team as a manager" -> team_id="...", user_id="...", role="team-manager"
Inputs: team_id (required), user_id (required), role.
umami_api_getRaw Umami API GETARead-onlyIdempotent
Make a read-only GET request against any Umami API endpoint that does not have a dedicated tool here.
Use this only as a fallback. The dedicated tools handle date parsing, website resolution, and formatting; this one does not. It is the right choice for endpoints such as /websites/:id/sessions/weekly, /websites/:id/session-data/properties, /websites/:id/session-data/values, /reports, /teams, /me, and anything added in a newer Umami release.
Timestamps in params must be epoch milliseconds, and website IDs must be UUIDs. Only GET is permitted, so this tool cannot create, update, or delete anything.
Args:
path (string, required): API path relative to the API root, for example '/websites/abc-123/sessions/weekly'. Do not include the /api prefix or the host.
params (object, optional): Query string parameters as string values, for example { startAt: '1735689600000', endAt: '1738368000000', timezone: 'America/New_York' }.
Returns: The raw JSON response from Umami, pretty-printed.
Examples:
Weekly session heatmap: path="/websites//sessions/weekly", params={ startAt: "...", endAt: "...", timezone: "America/New_York" }
Session property names: path="/websites//session-data/properties", params={ startAt: "...", endAt: "..." }
Current user: path="/me"
Error handling:
Rejects any path containing a query string; put parameters in 'params' instead.
Returns the Umami status code and path on failure, so a 404 usually means the endpoint does not exist on this Umami version.
Inputs: path (required), params.
umami_create_cohortCreate a cohort visible in the Umami UIA
Create a persisted audience Cohort (visitors who performed an action within a date range, optionally filtered further) that appears under Audience > Cohorts in the Umami UI.
Args:
website (string, optional): Website ID, name, or domain.
name (string, required): Display name for the cohort.
action_type ('path' | 'event', required): Whether the qualifying action is a page view or a custom event.
action_value (string, required): The page path (e.g. '/audit') or event name (e.g. 'signup').
date_range ('7day'|'30day'|'90day'|'6month'|'12month'): Window the action must fall in, default '30day'.
filters (array, optional): Additional filters, each { dimension, value, is_not? }.
match ('all' | 'any'): Whether every filter must match, or just one (default: 'all').
Returns: { "id": string, "name": string, "type": "cohort", "parameters": object }
Examples:
"Visitors who viewed /audit in the last 30 days" -> action_type='path', action_value='/audit'
"Mobile visitors who fired 'signup' in the last 90 days" -> action_type='event', action_value='signup', date_range='90day', filters=[{dimension:'device', value:'mobile'}]
Inputs: name (required), action_type (required), action_value (required), match, +3 more.
umami_create_funnelCreate a funnel visible in the Umami UIA
Create a persisted Funnel that appears under Behavior > Funnels in the Umami web UI, not just a computed result. Unlike umami_get_funnel (which computes step conversion on demand and shows nothing in the UI), this saves the funnel definition so it shows up for anyone browsing the dashboard.
Args:
website (string, optional): Website ID, name, or domain.
name (string, required): Display name for the funnel.
steps (array, required): 2-8 ordered steps, each { type: 'path' | 'event', value: string }.
window_minutes (number): Minutes a session has to complete all steps in order, default 60.
Returns: { "id": string, "name": string, "type": "funnel", "parameters": object }
Examples:
"/ -> /audit -> audit_submit funnel" -> steps=[{type:'path',value:'/'},{type:'path',value:'/audit'},{type:'event',value:'audit_submit'}]
Inputs: name (required), steps (required), website, window_minutes.
umami_create_goalCreate a goal visible in the Umami UIA
Create a persisted Goal that appears under Behavior > Goals in the Umami web UI, not just a computed result. Unlike umami_get_goal (which computes a conversion rate on demand and shows nothing in the UI), this saves the goal definition so it shows up for anyone browsing the dashboard.
Args:
website (string, optional): Website ID, name, or domain.
name (string, required): Display name for the goal.
match_type ('path' | 'event', required): Whether the goal is reaching a page or firing a custom event.
value (string, required): The page path (e.g. '/thank-you') or event name (e.g. 'signup') to match.
Returns: { "id": string, "name": string, "type": "goal", "parameters": object }
Error handling:
match_type='event' accepts any event name, even one that has never fired yet; the goal will just show 0 conversions until it does.
Inputs: name (required), value (required), match_type (required), website.
umami_create_segmentCreate a segment visible in the Umami UIA
Create a persisted audience Segment (a saved filter combination) that appears under Audience > Segments in the Umami UI.
Args:
website (string, optional): Website ID, name, or domain.
name (string, required): Display name for the segment.
filters (array, required): 1+ filters, each { dimension, value, is_not? }. Dimension is one of: path, referrer, title, query, browser, os, device, country, region, city, language, hostname, tag, event, distinctId, utmSource, utmMedium, utmCampaign, utmContent, utmTerm, segment, cohort.
match ('all' | 'any'): Whether every filter must match, or just one (default: 'all').
Returns: { "id": string, "name": string, "type": "segment", "parameters": object }
Examples:
"Mobile visitors" -> filters=[{dimension:'device', value:'mobile'}]
"Paid social, not from the US" -> filters=[{dimension:'utmMedium', value:'paid'}, {dimension:'country', value:'US', is_not:true}], match='all'
Inputs: name (required), filters (required), match, website.
umami_create_teamCreate a teamA
Create a team in Umami. Teams group websites and members under shared access, separate from personal accounts. Useful for keeping one client's or one product line's websites together with a dedicated access code.
Args:
name (string, required): Team name.
Returns: { "id": string, "name": string, "access_code": string }
The access_code can be shared with someone else so they can self-join via umami_join_team, instead of you adding them one by one.
Examples:
"Create a team to hold all the Gradeline sites" -> name="Gradeline"
Inputs: name (required).
umami_create_userCreate an Umami loginA
Create a new login account on this self-hosted Umami instance. This is for internal team members who need their own login, not for issuing client-facing accounts.
Admin access required. Not available on Umami Cloud.
Args:
username (string, required): Login username.
password (string, required): Login password. The user can change it after logging in.
role ('admin' | 'user' | 'view-only'): Instance-wide role (default: 'user'). 'admin' can manage all users and websites; 'user' can manage their own websites; 'view-only' can only view.
id (string, optional): Force a specific UUID for the user.
Returns: { "id": string, "username": string, "role": string }
Examples:
"Create a login for the new ops hire" -> username="jordan", password="", role="user"
Error handling:
Fails with a 400 if the username is already taken.
Fails with 403 if the calling account is not an Umami admin.
Inputs: password (required), username (required), id, role.
umami_create_websiteCreate a website in UmamiA
Register a new website for tracking in Umami. This is the first step in onboarding a client or project: it returns a website ID that goes into the tracking script, and that every stats tool in this server uses.
Args:
name (string, required): Display name for the website.
domain (string, required): The domain being tracked, e.g. 'example.com'. No protocol.
team_id (string, optional): Create the website under a team instead of your personal account. Use umami_list_teams to find the ID.
id (string, optional): Force a specific UUID for the website, for example to match an ID reserved elsewhere.
Returns: JSON shape: { "id": string, "name": string, "domain": string, "team_id": string | null, "created_at": string, "tracking_snippet": string }
Examples:
"Set up tracking for the new client site" -> name="Walker's Land Services", domain="walkerslandservices.com"
"Add this under the Gradeline team" -> name="Gradeline", domain="gradeline.info", team_id=""
Error handling:
Fails if a website with the same forced 'id' already exists.
Not available on Umami Cloud in read-only API-key mode without appropriate account permissions.
Inputs: name (required), domain (required), id, team_id.
umami_delete_saved_reportDelete a saved goal, funnel, journey, or retention reportADestructiveIdempotent
Permanently delete a saved report (goal, funnel, journey, or retention) so it no longer appears in the Umami UI. Get the report ID from umami_list_saved_reports. For a segment or cohort, use umami_delete_segment_cohort instead.
This cannot be undone. Requires confirm=true.
Args:
report_id (string, required): The report's ID.
confirm (boolean, required): Must be true. There is no undo.
Returns: { "ok": true, "report_id": string }
Inputs: confirm (required), report_id (required).
umami_delete_segment_cohortDelete a saved segment or cohortADestructiveIdempotent
Permanently delete a saved Segment or Cohort so it no longer appears in the Umami UI. Get the ID from umami_list_segments_cohorts.
This cannot be undone. Requires confirm=true.
Args:
website (string, optional): Website ID, name, or domain.
report_id (string, required): The segment/cohort's ID.
confirm (boolean, required): Must be true. There is no undo.
Returns: { "ok": true, "report_id": string }
Inputs: confirm (required), report_id (required), website.
umami_delete_teamDelete a teamADestructiveIdempotent
Permanently delete a team. Websites owned by the team are not deleted, but become inaccessible through it; reassign them first if they still need a home.
This cannot be undone. Requires confirm=true.
Args:
team_id (string, required): Team UUID.
confirm (boolean, required): Must be true. There is no undo.
Returns: { "ok": true, "team_id": string }
Inputs: confirm (required), team_id (required).
umami_delete_userDelete an Umami userADestructiveIdempotent
Permanently delete a login account from this self-hosted Umami instance. The websites they own are not deleted, but become inaccessible to them.
This cannot be undone. Requires confirm=true. Admin access required. Not available on Umami Cloud.
Args:
user_id (string, required): User UUID.
confirm (boolean, required): Must be true. There is no undo.
Returns: { "ok": true, "user_id": string }
Inputs: confirm (required), user_id (required).
umami_delete_websiteDelete a websiteADestructiveIdempotent
Permanently delete a website registration and all of its collected data from Umami.
This cannot be undone. Requires confirm=true. To keep the registration and tracking ID but clear historical data, use umami_reset_website instead.
Args:
website (string, required): Website ID, name, or domain.
confirm (boolean, required): Must be true. There is no undo.
Returns: { "ok": true, "website_id": string }
Examples:
"Remove the old staging site from Umami entirely" -> website="staging.example.com", confirm=true
Inputs: confirm (required), website.
umami_get_active_visitorsGet active visitorsARead-only
Get the number of unique visitors active on a website in the last 5 minutes.
This is the realtime counter only. For traffic over a period use umami_get_stats.
Args:
website (string, optional): Website ID, name, or domain.
Returns: JSON shape: { "website_id": string, "active_visitors": number, "window": "last 5 minutes" }
Examples:
"How many people are on the site right now?" -> website="example.com"
Inputs: website.
umami_get_click_heatmapGet a click heatmap for a pageARead-onlyIdempotent
Get a click-density heatmap for one page path, built from recorded session replays.
Umami has no dedicated heatmap endpoint. Click coordinates are captured inside session replay recordings, so this filters replays to the given path, downloads them (capped by max_replays), extracts every click's (x, y) position, normalizes it against that recording's viewport size, and buckets it into a grid.
Args:
website (string, optional): Website ID, name, or domain.
path (string, required): Exact page path to build the heatmap for, e.g. '/pricing'.
range (string): Date range, default '30d' (replay volume is usually much lower than pageview volume).
start_date / end_date (string, optional): Explicit bounds, overriding 'range'.
grid_size (number): Buckets per axis, default 10 (a 10x10 grid), max 20.
max_replays (number): Cap on replays downloaded, default 100, max 300.
response_format ('markdown' | 'json'): Output format (default: 'markdown').
Returns: JSON shape: { "path": string, "sample_replays": number, "replays_with_clicks": number, "total_clicks": number, "grid_size": number, "cells": [ { "row": number, "col": number, "x_pct_range": [number, number], "y_pct_range": [number, number], "clicks": number } ] }
Error handling:
Zero clicks usually means recording is off for this page's traffic, sampling missed it, or no one has clicked yet; check umami_list_replays for that path first.
Inputs: path (required), range, website, end_date, +4 more.
umami_get_events_seriesGet custom events over timeARead-onlyIdempotent
Get counts of custom tracked events bucketed over time, grouped by event name.
Use this for conversion and interaction tracking: form submits, button clicks, signups, or any event fired through umami.track().
Args:
website (string, optional): Website ID, name, or domain.
range (string): Date range, default '7d'.
start_date / end_date (string, optional): Explicit bounds, overriding 'range'.
unit ('minute' | 'hour' | 'day' | 'month' | 'year', optional): Bucket size, chosen automatically if omitted.
event (string, optional): Restrict to a single event name.
filters (object, optional): Segment filters.
timezone (string, optional): IANA timezone.
response_format ('markdown' | 'json'): Output format (default: 'markdown').
Returns: JSON shape: { "website_id": string, "unit": string, "totals_by_event": { "": number }, "series": [ { "event": string, "timestamp": string, "count": number } ] }
Examples:
"How many contact form submits last week?" -> range="last_week", event="contact-form-submit"
"Which events fire most often?" -> range="30d"
Inputs: unit, event, range, filters, +5 more.
umami_get_funnelGet funnel conversion across ordered stepsARead-onlyIdempotent
Get session counts and drop-off across an ordered sequence of pages and/or custom events.
Umami has no funnel endpoint, so this walks every session's activity trail in the range (capped by max_sessions) looking for the steps in order. A step matches a page path or a custom event name, whichever it equals; a session only advances once it has completed the previous step.
Args:
website (string, optional): Website ID, name, or domain.
steps (string[], required): 2-8 steps in order, each a page path (e.g. '/pricing') or event name (e.g. 'signup').
range (string): Date range, default '7d'.
start_date / end_date (string, optional): Explicit bounds, overriding 'range'.
filters (object, optional): Segment filters applied to the session pool, e.g. { device: 'mobile' }.
max_sessions (number): Cap on sessions scanned, default 500, max 2000.
response_format ('markdown' | 'json'): Output format (default: 'markdown').
Returns: JSON shape: { "steps": [ { "step": string, "sessions": number, "pct_of_first": number, "pct_of_previous": number } ], "scanned_sessions": number, "total_sessions_in_range": number, "truncated": boolean }
Examples:
"Funnel from pricing to signup to activation" -> steps=["/pricing", "/signup", "activation"]
Error handling:
If 'truncated' is true, total sessions in the range exceeded max_sessions; raise it for a more complete picture, at the cost of more API calls.
Inputs: steps (required), range, filters, website, +4 more.
umami_get_goalGet conversion rate toward a goalARead-onlyIdempotent
Get the conversion rate for a single-step goal: visitors who reached a page, versus all visitors in the same range.
A goal is either a page ('path') or a custom event ('event'). Pass exactly one. Umami has no dedicated goals feature, so this is computed by comparing two filtered calls to the stats endpoint.
Args:
website (string, optional): Website ID, name, or domain.
path (string): Goal is reaching this page, e.g. '/thank-you'. Exactly one of path/event required.
event (string): Goal is firing this custom event, e.g. 'signup'. Exactly one of path/event required.
range (string): Date range, default '7d'.
start_date / end_date (string, optional): Explicit bounds, overriding 'range'.
filters (object, optional): Segment filters applied to both the goal and the baseline, e.g. { country: 'US' }.
response_format ('markdown' | 'json'): Output format (default: 'markdown').
Returns: JSON shape: { "goal": { "type": "path"|"event", "value": string }, "baseline_visitors": number, "goal_visitors": number, "conversion_rate_pct": number }
Examples:
"What % of visitors reach the thank-you page?" -> path="/thank-you"
"Conversion rate on the signup event this month" -> event="signup", range="this_month"
Error handling:
A goal event with zero occurrences usually means the tracker never fired umami.track(event_name) in the range, not an error.
Inputs: path, event, range, filters, +4 more.
umami_get_journeysGet common page-visit sequencesARead-onlyIdempotent
Get the most common sequences of pages visitors take through the site.
Umami has no journey/path-analysis endpoint, so this walks every session's activity trail in the range (capped by max_sessions), reduces each to its ordered page paths (consecutive repeats collapsed), truncates to 'depth' steps, and ranks the most frequent sequences.
Args:
website (string, optional): Website ID, name, or domain.
start_path (string, optional): Only include sessions whose first page matches this path, e.g. '/'.
depth (number): Steps per sequence shown, default 4, max 8.
limit (number): Top N sequences to return, default 10, max 50.
range (string): Date range, default '7d'.
start_date / end_date (string, optional): Explicit bounds, overriding 'range'.
filters (object, optional): Segment filters applied to the session pool.
max_sessions (number): Cap on sessions scanned, default 500, max 2000.
response_format ('markdown' | 'json'): Output format (default: 'markdown').
Returns: JSON shape: { "sequences": [ { "path": string, "sessions": number, "pct": number } ], "matched_sessions": number, "scanned_sessions": number, "total_sessions_in_range": number, "truncated": boolean }
Examples:
"What do people do after landing on the homepage?" -> start_path="/", depth=3
Inputs: depth, limit, range, filters, +6 more.
umami_get_metricsGet ranked traffic breakdownARead-onlyIdempotent
Get a ranked breakdown of traffic by one dimension: top pages, referrers, countries, browsers, devices, acquisition channels, custom events, and more.
This is the workhorse for "top N" questions. Set expanded=true when you need engagement quality per row (pageviews, visitors, visits, bounces, time on site) rather than just a visitor count, for example to find which landing page bounces hardest.
Args:
website (string, optional): Website ID, name, or domain.
type (string, required): Dimension to break down by. 'path' (pages), 'entry' (landing pages), 'exit', 'referrer', 'channel', 'domain', 'country', 'region', 'city', 'browser', 'os', 'device', 'language', 'screen', 'title', 'query', 'event', 'hostname', 'tag', 'distinctId'.
range (string): Date range, default '7d'.
start_date / end_date (string, optional): Explicit bounds, overriding 'range'.
expanded (boolean): Return per-row engagement metrics instead of a single count (default: false).
limit (number): Rows to return, 1-500 (default: 20).
offset (number): Rows to skip for pagination (default: 0).
filters (object, optional): Segment filters, for example { country: 'US' } to see top pages among US visitors.
response_format ('markdown' | 'json'): Output format (default: 'markdown').
Returns: Plain JSON shape: { "type": string, "count": number, "rows": [ { "name": string, "visitors": number, "share_pct": number } ], "has_more": boolean, "next_offset": number } Expanded JSON shape: { "type": string, "count": number, "rows": [ { "name": string, "pageviews": number, "visitors": number, "visits": number, "bounces": number, "bounce_rate_pct": number, "avg_visit_duration_seconds": number } ], ... }
Examples:
"What are our top 10 pages this month?" -> type="path", range="this_month", limit=10
"Where is traffic coming from?" -> type="referrer", range="30d"
"Which landing page has the worst bounce rate?" -> type="entry", expanded=true
"Top pages for mobile visitors in Florida" -> type="path", filters={ device: "mobile", region: "US-FL" }
Error handling:
Returns "No data" when the dimension has no rows in the range, which is expected for 'event' when no custom events are tracked.
Inputs: type (required), limit, range, offset, +6 more.
umami_get_pageviews_seriesGet pageview time seriesARead-onlyIdempotent
Get pageviews and sessions bucketed over time, for trend and seasonality questions.
Use this when the question is about shape over time rather than a single total: which day spiked, whether traffic is trending up, what the weekday pattern looks like.
Args:
website (string, optional): Website ID, name, or domain.
range (string): Date range, default '7d'.
start_date / end_date (string, optional): Explicit bounds, overriding 'range'.
unit ('minute' | 'hour' | 'day' | 'month' | 'year', optional): Bucket size. Chosen automatically if omitted. Umami caps minute at 60 minutes, hour at 30 days, day at 6 months.
filters (object, optional): Segment filters.
timezone (string, optional): IANA timezone for bucket boundaries.
response_format ('markdown' | 'json'): Output format (default: 'markdown').
Returns: JSON shape: { "website_id": string, "unit": string, "points": [ { "timestamp": string, "pageviews": number, "sessions": number } ], "totals": { "pageviews": number, "sessions": number }, "peak": { "timestamp": string, "pageviews": number } }
Examples:
"Show daily traffic for the last 30 days" -> range="30d", unit="day"
"What hour of the day is busiest?" -> range="24h", unit="hour"
Inputs: unit, range, filters, website, +4 more.
umami_get_recorder_configGet the live session replay / heatmap configARead-onlyIdempotent
Get the recorder configuration Umami is actually serving to the tracker for a website: whether replay and heatmaps are enabled, sample rates, masking level, max duration, and the block selector.
This reads the same public endpoint the tracker script itself calls, so it is the ground truth after umami_update_website changes replay or heatmap settings, useful for confirming values actually took effect and resolving any unit ambiguity on max duration.
Args:
website (string, optional): Website ID, name, or domain.
Returns: JSON shape: { "enabled": boolean, "replay_enabled": boolean, "heatmap_enabled": boolean, "sample_rate": number, "heatmap_sample_rate": number, "mask_level": string, "max_duration": number, "block_selector": string }
Examples:
"Did the replay settings actually save?" -> website="example.com"
Inputs: website.
umami_get_replayGet a session replay summaryARead-onlyIdempotent
Summarize one recorded session replay: pages visited, click count, and a duration/event breakdown.
This does not return the raw rrweb event stream (it can be tens of thousands of events); it summarizes it. Get replay IDs from umami_list_replays with response_format='json'.
Args:
website (string, optional): Website ID, name, or domain.
replay_id (string, required): Replay UUID.
include_clicks (boolean): Include the raw click coordinates (default: false, capped at 200).
response_format ('markdown' | 'json'): Output format (default: 'markdown').
Returns: JSON shape: { "session_id": string, "pages": [ { "href": string, "at": string } ], "click_count": number, "clicks": [ { "x": number, "y": number, "pathname": string } ] | undefined }
Inputs: replay_id (required), website, include_clicks, response_format.
umami_get_retentionGet visitor retention across periodsARead-onlyIdempotent
Get a cohort retention curve: of the distinct visitors seen in the first period, what percentage returned in each period since.
Umami has no retention endpoint. This is built from umami.identify()'d visitors: it groups the 'distinctId' metric dimension by period and measures overlap between the earliest period's cohort and each later period.
Requires the site to call umami.identify(persistentId) with a stable, persistent ID (e.g. a long-lived cookie or logged-in user ID). Without that, every session has a null distinctId and no cohort can be tracked, this will report zero visitors regardless of real traffic.
Args:
website (string, optional): Website ID, name, or domain.
cohort_unit ('day' | 'week' | 'month'): Length of each period, default 'week'.
periods (number): Number of periods to show, including period 0, default 6, max 12.
response_format ('markdown' | 'json'): Output format (default: 'markdown').
Returns: JSON shape: { "cohort_unit": string, "cohort_size": number, "cohort_start": string, "periods": [ { "period": number, "period_start": string, "returning_visitors": number, "retention_pct": number } ] }
Error handling:
cohort_size of 0 means no visitor has been identify()'d yet in the earliest period. This is an instrumentation gap, not a data gap; pageview/session tools still work without identify().
Inputs: periods, website, cohort_unit, response_format.
umami_get_revenueGet revenue attributed from a custom event propertyARead-onlyIdempotent
Get total and average revenue from a numeric custom-event property, e.g. an 'amount' field on a 'purchase' event.
Self-hosted Umami has no built-in revenue tracking. This works by reading the distribution of a numeric property recorded on a custom event, via umami.track(event_name, { [property]: amount }). It sums (value x occurrence count) across every recorded value.
Args:
website (string, optional): Website ID, name, or domain.
event (string, required): Custom event name, e.g. 'purchase'.
property (string, required): Numeric property on that event holding the amount, e.g. 'amount'.
range (string): Date range, default '30d'.
start_date / end_date (string, optional): Explicit bounds, overriding 'range'.
filters (object, optional): Segment filters, e.g. { utmSource: 'google' } for revenue by campaign.
response_format ('markdown' | 'json'): Output format (default: 'markdown').
Returns: JSON shape: { "event": string, "property": string, "total_revenue": number, "transaction_count": number, "average_value": number }
Error handling:
total_revenue of 0 usually means the tracker has never called umami.track(event, { property: number }) in this range, not an error. Check umami_get_metrics with type='event' to confirm the event fires at all.
Inputs: event (required), property (required), range, filters, +4 more.
umami_get_sessionGet session detail and activityARead-onlyIdempotent
Get details for one visitor session, optionally including the full page-by-page activity trail.
Use this to trace an individual journey through the site: entry page, path taken, events fired, exit point. Get session IDs from umami_list_sessions with response_format='json'.
Args:
website (string, optional): Website ID, name, or domain.
session_id (string, required): Session UUID.
include_activity (boolean): Include the chronological page and event trail (default: true).
range (string): Date range to search for activity, default '30d'. Activity outside this range is not returned.
response_format ('markdown' | 'json'): Output format (default: 'markdown').
Returns: JSON shape: { "session": { "id": string, "country": string, "device": string, "browser": string, "os": string, "first_at": string, "last_at": string, "visits": number, "views": number, "events": number, "totaltime": number }, "activity": [ { "created_at": string, "url_path": string, "referrer_domain": string, "event_name": string } ] }
Examples:
"What did session abc123 do on the site?" -> session_id="abc123...", include_activity=true
Inputs: session_id (required), range, website, response_format, +1 more.
umami_get_statsGet website traffic statsARead-onlyIdempotent
Get summary traffic statistics for a website over a date range, with optional comparison to the immediately preceding period.
This is the headline-numbers tool: pageviews, visitors, visits, bounce rate, and average visit duration. Bounce rate and average visit duration are derived here, since Umami returns raw bounce and total-time counts.
Args:
website (string, optional): Website ID, name, or domain.
range (string): Date range, default '7d'. Relative ('24h', '7d', '30d'), named ('today', 'yesterday', 'last_week', 'last_month', 'mtd', 'ytd'), or use start_date/end_date.
start_date / end_date (string, optional): Explicit bounds, overriding 'range'.
compare (boolean): Also return the previous period of equal length with percent change (default: true).
filters (object, optional): Segment filters such as { country: 'US', path: '/pricing' }.
timezone (string, optional): IANA timezone for day boundaries.
response_format ('markdown' | 'json'): Output format (default: 'markdown').
Returns: JSON shape: { "website_id": string, "range": { "start": string, "end": string }, "stats": { "pageviews": number, "visitors": number, "visits": number, "bounces": number, "totaltime": number, "bounce_rate_pct": number, "views_per_visit": number, "avg_visit_duration_seconds": number }, "previous": { ...same fields... } | null, "change": { "pageviews": string, "visitors": string, "visits": string, "bounce_rate_pct": string } | null }
Examples:
"How did the site do last month?" -> range="last_month"
"Traffic from mobile users in the US this week" -> range="this_week", filters={ device: "mobile", country: "US" }
"Compare this month to last" -> range="mtd", compare=true
Error handling:
Returns a 404 error if the website ID does not exist.
All-zero results usually mean the range predates tracking; check umami_get_website for the available data range.
Inputs: range, compare, filters, website, +4 more.
umami_get_teamGet team details and membersARead-onlyIdempotent
Get a team's details, including its full member list and roles.
Args:
team_id (string, required): Team UUID. Get this from umami_list_teams.
response_format ('markdown' | 'json'): Output format (default: 'markdown').
Returns: JSON shape: { "id": string, "name": string, "access_code": string, "members": [ { "user_id": string, "username": string, "role": string } ] }
Inputs: team_id (required), response_format.
umami_get_team_websitesList a team's websitesARead-onlyIdempotent
List every website belonging to a team.
Args:
team_id (string, required): Team UUID.
search (string, optional): Case-insensitive substring to filter by name or domain.
response_format ('markdown' | 'json'): Output format (default: 'markdown').
Returns: JSON shape: { "count": number, "websites": [ { "id": string, "name": string, "domain": string } ] }
Inputs: team_id (required), search, response_format.
umami_get_userGet an Umami user's detailsARead-onlyIdempotent
Get a login account's details, plus the websites and teams it has access to.
Admin access required for other users; any authenticated user can look up themselves. Not available on Umami Cloud.
Args:
user_id (string, required): User UUID. Get this from umami_list_users.
response_format ('markdown' | 'json'): Output format (default: 'markdown').
Returns: JSON shape: { "id": string, "username": string, "role": string, "created_at": string, "websites": [ { "id": string, "name": string, "domain": string } ], "teams": [ { "id": string, "name": string } ] }
Inputs: user_id (required), response_format.
umami_get_websiteGet Umami website detailsARead-onlyIdempotent
Get configuration details for one website plus the date range of data actually collected for it.
The date range matters: querying a period before tracking started returns zeros, which is easy to misread as a traffic collapse. Check this first when numbers look surprisingly empty.
Args:
website (string, optional): Website ID, name, or domain.
response_format ('markdown' | 'json'): Output format (default: 'markdown').
Returns: JSON shape: { "id": string, "name": string, "domain": string, "share_id": string | null, "created_at": string, "data_start": string | null, "data_end": string | null, "active_visitors": number }
Examples:
"When did we start tracking example.com?" -> website="example.com"
"Is anyone on the site right now?" -> website="example.com"
Inputs: website, response_format.
umami_join_teamJoin a team via access codeAIdempotent
Join a team as the currently authenticated user, using its access code. This is the self-serve counterpart to umami_add_team_user, which an existing team manager uses to add someone else directly.
Args:
access_code (string, required): The team's access code, from umami_create_team or umami_get_team.
Returns: { "team_id": string, "user_id": string, "role": string }
Inputs: access_code (required).
umami_list_replaysList session replay recordingsARead-onlyIdempotent
List recorded session replays for a website over a date range, newest first.
Replays only exist where recording is enabled (umami_get_recorder_config) and a session was sampled. Use umami_get_replay to inspect one in detail.
Args:
website (string, optional): Website ID, name, or domain.
range (string): Date range, default '7d'.
start_date / end_date (string, optional): Explicit bounds, overriding 'range'.
page (number): Page number, 1-based (default: 1).
page_size (number): Recordings per page, 1-100 (default: 20).
response_format ('markdown' | 'json'): Output format (default: 'markdown').
Returns: JSON shape: { "total": number, "page": number, "page_size": number, "replays": [ { "id": string, "session_id": string, "device": string, "browser": string, "os": string, "country": string, "duration_seconds": number, "event_count": number, "started_at": string } ] }
Error handling:
An empty result usually means recording is off for this website, or no session was sampled in the range. Check umami_get_recorder_config.
Inputs: page, range, website, end_date, +3 more.
umami_list_saved_reportsList saved goals, funnels, journeys, or retention reportsARead-onlyIdempotent
List the saved reports of one type for a website, as they appear in the Umami UI sidebar (Goals, Funnels, Journeys, Retention). For Segments or Cohorts, use umami_list_segments_cohorts instead — they live on a different endpoint.
Args:
website (string, optional): Website ID, name, or domain.
type (string, required): One of 'goal', 'funnel', 'journey', 'retention'.
response_format ('markdown' | 'json'): Output format (default: 'markdown').
Returns: JSON shape: { "reports": [ { "id": string, "name": string, "type": string, "parameters": object, "created_at": string } ] }
Inputs: type (required), website, response_format.
umami_list_segments_cohortsList saved segments or cohortsARead-onlyIdempotent
List the saved Segments or Cohorts for a website, as they appear under Audience in the Umami UI.
Args:
website (string, optional): Website ID, name, or domain.
type ('segment' | 'cohort', required): Which kind to list.
response_format ('markdown' | 'json'): Output format (default: 'markdown').
Returns: JSON shape: { "reports": [ { "id": string, "name": string, "type": string, "parameters": object, "created_at": string } ] }
Inputs: type (required), website, response_format.
umami_list_sessionsList visitor sessionsARead-onlyIdempotent
List individual visitor sessions for a website over a date range, newest first.
Sessions are anonymous. Use this to inspect real visit behaviour rather than aggregates: how many pages a typical visit covers, where high-engagement visitors come from, or what a spike actually consisted of.
Args:
website (string, optional): Website ID, name, or domain.
range (string): Date range, default '7d'.
start_date / end_date (string, optional): Explicit bounds, overriding 'range'.
search (string, optional): Free-text search across session attributes.
page (number): Page number, 1-based (default: 1).
page_size (number): Sessions per page, 1-100 (default: 20).
filters (object, optional): Segment filters such as { country: 'US' }.
response_format ('markdown' | 'json'): Output format (default: 'markdown').
Returns: JSON shape: { "total": number, "page": number, "page_size": number, "sessions": [ { "id": string, "country": string, "city": string, "device": string, "browser": string, "os": string, "first_at": string, "last_at": string, "visits": number, "views": number } ], "has_more": boolean }
Examples:
"Show me sessions from yesterday" -> range="yesterday"
"Which visits looked at the most pages this week?" -> range="this_week", page_size=50
Error handling:
Returns an empty result set when no sessions occurred in the range.
Inputs: page, range, search, filters, +5 more.
umami_list_teamsList teamsARead-onlyIdempotent
List every team on this Umami account, with member and website counts.
Args:
limit (number): Rows to return, 1-500 (default: 20).
offset (number): Rows to skip, converted to a page number (default: 0).
response_format ('markdown' | 'json'): Output format (default: 'markdown').
Returns: JSON shape: { "count": number, "teams": [ { "id": string, "name": string, "access_code": string, "website_count": number, "member_count": number } ] }
Examples:
"What teams do we have set up?" -> no arguments
Inputs: limit, offset, response_format.
umami_list_usersList all Umami usersARead-onlyIdempotent
List every login account on this self-hosted Umami instance.
Admin access required. Not available on Umami Cloud.
Args:
response_format ('markdown' | 'json'): Output format (default: 'markdown').
Returns: JSON shape: { "count": number, "users": [ { "id": string, "username": string, "role": string, "created_at": string } ] }
Examples:
"Who has a login to our Umami?" -> no arguments
Inputs: response_format.
umami_list_websitesList Umami websitesARead-onlyIdempotent
List every website tracked in this Umami account, including websites owned by teams.
Start here when you do not already know a website ID. Every other tool accepts a website ID, name, or domain, so this tool is what turns "the marketing site" into something queryable.
Args:
search (string, optional): Case-insensitive substring matched against name and domain.
response_format ('markdown' | 'json'): Output format (default: 'markdown').
Returns: JSON shape: { "count": number, "websites": [ { "id": string, "name": string, "domain": string, "created_at": string, "team_id": string | null } ] }
Examples:
"What sites do I have in Umami?" -> no arguments
"Find the website for example.com" -> search="example.com"
Error handling:
Returns an authentication error if the API key or login is rejected.
Returns "No websites found" when the account has none.
Inputs: search, response_format.
umami_onboard_clientOnboard a client: website, team, and access in one callA
Set up everything Umami needs for a new client or project in a single call: register the website, optionally create a dedicated team for it, and optionally grant an existing internal user access to that team.
This is the fast path for "get this new site tracked and set up properly." For anything more custom, for example multiple websites under one team, use umami_create_website, umami_create_team, and umami_add_team_user individually.
Args:
website_name (string, required): Display name for the website.
domain (string, required): Domain being tracked, e.g. 'example.com'. No protocol.
team_name (string, optional): If given, creates a new team with this name and puts the website under it. Omit to create the website under your personal account instead.
grant_user_id (string, optional): An existing internal user (from umami_list_users) to add to the new team.
grant_role ('team-manager' | 'team-member' | 'team-view-only'): Role for grant_user_id on the new team (default: 'team-manager'). Ignored if grant_user_id or team_name is omitted.
replay_enabled (boolean, optional): Turn on session replay recording for the new website.
heatmap_enabled (boolean, optional): Turn on heatmap collection for the new website.
sample_rate (number, optional): Fraction of sessions to record for replay, 0 to 1. Only applied if replay_enabled or heatmap_enabled is set.
mask_level ('strict' | 'moderate', optional): PII masking strictness for replay recordings.
Returns: JSON shape: { "website": { "id": string, "name": string, "domain": string }, "team": { "id": string, "name": string, "access_code": string } | null, "granted_user": { "id": string, "username": string, "role": string } | null, "replay_config": { "replayEnabled": boolean, "heatmapEnabled": boolean, "sampleRate": number, "maskLevel": string } | null, "tracking_snippet": string }
Examples:
"Set up tracking for the new Walker's Land Services site, its own team, and add jordan to it" -> website_name="Walker's Land Services", domain="walkerslandservices.com", team_name="Walker's Land Services", grant_user_id="<jordan's user id>"
"Just get this client tracked, no team needed" -> website_name="...", domain="..."
"Set it up with replay on at 15% from day one" -> website_name="...", domain="...", replay_enabled=true, sample_rate=0.15
Error handling:
If website creation succeeds but team creation fails, the website still exists; the response reports the partial result rather than leaving it unclear.
If the website is created but the replay/heatmap follow-up update fails, the website and team (if any) still exist; use umami_update_website to finish that step manually.
Inputs: domain (required), website_name (required), team_name, grant_role, +5 more.
umami_remove_team_userRemove a user from a teamADestructiveIdempotent
Remove a member from a team. Their login and any websites they personally own are unaffected; they simply lose access to the team's shared websites.
Requires confirm=true.
Args:
team_id (string, required): Team UUID.
user_id (string, required): User UUID to remove.
confirm (boolean, required): Must be true.
Returns: { "ok": true, "team_id": string, "user_id": string }
Inputs: confirm (required), team_id (required), user_id (required).
umami_reset_websiteReset a website (delete all data)ADestructiveIdempotent
Permanently delete all collected data for a website: every pageview, session, and event. The website registration and tracking ID are kept, so the tracking script keeps working and data collection starts fresh.
This cannot be undone. Requires confirm=true.
Args:
website (string, required): Website ID, name, or domain.
confirm (boolean, required): Must be true. There is no undo.
Returns: { "ok": true, "website_id": string }
Examples:
"Wipe the test data we collected before going live" -> website="example.com", confirm=true
Inputs: confirm (required), website.
umami_traffic_reportFull traffic reportARead-onlyIdempotent
Build a complete traffic report for a website in one call: headline stats, period-over-period change, and ranked breakdowns for top pages, landing pages, referrers, acquisition channels, countries, devices, and browsers.
Prefer this over chaining umami_get_stats and several umami_get_metrics calls when the question is broad, for example "how is the site doing" or "give me last month's analytics". Use the individual tools instead when you need one specific dimension, deeper pagination, or expanded engagement metrics.
Args:
website (string, optional): Website ID, name, or domain.
range (string): Date range, default '30d'.
start_date / end_date (string, optional): Explicit bounds, overriding 'range'.
breakdowns (array of strings, optional): Which dimensions to include. Defaults to path, entry, referrer, channel, country, device, browser.
limit (number): Rows per breakdown, 1-50 (default: 10).
compare (boolean): Include the previous period of equal length with percent change (default: true).
filters (object, optional): Segment filters applied to every part of the report.
response_format ('markdown' | 'json'): Output format (default: 'markdown').
Returns: JSON shape: { "website": string, "range": { "start": string, "end": string }, "stats": { "pageviews": number, "visitors": number, "visits": number, "bounce_rate_pct": number, "avg_visit_duration_seconds": number }, "change": { "pageviews": string, "visitors": string, "visits": string } | null, "breakdowns": { "": [ { "name": string, "visitors": number, "share_pct": number } ] } }
Examples:
"Give me the analytics rundown for last month" -> range="last_month"
"How did the site do this week versus last?" -> range="this_week", compare=true
"Full report for US mobile traffic" -> filters={ country: "US", device: "mobile" }
Error handling:
Individual breakdowns that fail are omitted rather than failing the whole report; the response notes which ones were skipped.
Inputs: limit, range, compare, filters, +5 more.
umami_update_teamRename a team or rotate its access codeAIdempotent
Update a team's name, or set a new access code.
Args:
team_id (string, required): Team UUID.
name (string, optional): New team name.
access_code (string, optional): New access code for self-join links. Rotating it invalidates the old code.
Returns: { "id": string, "name": string, "access_code": string }
Inputs: team_id (required), name, access_code.
umami_update_team_userChange a team member's roleAIdempotent
Change an existing team member's role.
Args:
team_id (string, required): Team UUID.
user_id (string, required): User UUID whose role should change.
role ('team-manager' | 'team-member' | 'team-view-only', required): New role.
Returns: { "team_id": string, "user_id": string, "role": string }
Inputs: role (required), team_id (required), user_id (required).
umami_update_userUpdate an Umami userAIdempotent
Change a login account's username, password, or instance-wide role.
Admin access required. Not available on Umami Cloud.
Args:
user_id (string, required): User UUID.
username (string, optional): New username.
password (string, optional): New password.
role ('admin' | 'user' | 'view-only', optional): New instance-wide role.
Returns: { "id": string, "username": string, "role": string }
Examples:
"Promote jordan to admin" -> user_id="...", role="admin"
"Reset their password" -> user_id="...", password=""
Inputs: user_id (required), role, password, username.
umami_update_websiteUpdate a website's configurationAIdempotent
Update a website's name, domain, public share link, or full session replay and heatmap configuration.
Covers every field Umami exposes for a website's recording setup, not just the on/off switches: sampling rates, PII masking strictness, max recording length, and a CSS selector to exclude sensitive elements (payment forms, etc.) from capture. Pass only the fields you want to change; anything omitted is left as-is. Use umami_get_recorder_config afterward to confirm exactly what the tracker will receive.
Args:
website (string, required): Website ID, name, or domain.
name (string, optional): New display name.
domain (string, optional): New domain.
share_id (string, optional): Set a custom share slug to enable a public dashboard link. Pass an empty string to disable sharing.
replay_enabled (boolean, optional): Enable or disable session replay recording.
heatmap_enabled (boolean, optional): Enable or disable heatmap data collection.
sample_rate (number, optional): Fraction of sessions to record for replay, 0 to 1.
heatmap_sample_rate (number, optional): Fraction of sessions to record for heatmaps, 0 to 1.
mask_level ('strict' | 'moderate', optional): PII masking strictness for replay recordings. 'strict' masks more aggressively.
max_duration_ms (number, optional): Maximum length of a single recording, in milliseconds. Umami's own docs are inconsistent about whether this field is ms or seconds; umami_get_recorder_config after saving shows the effective value the tracker will actually use.
block_selector (string, optional): CSS selector for elements to exclude entirely from replay capture, e.g. '.payment-form, [data-sensitive]'.
Returns: JSON shape: { "id": string, "name": string, "domain": string, "share_id": string | null, "replay_config": { "replayEnabled": boolean, "heatmapEnabled": boolean, "sampleRate": number, "heatmapSampleRate": number, "maskLevel": string, "maxDuration": number, "blockSelector": string } | null }
Examples:
"Turn on session replay for the Gradeline site at 20% sampling" -> replay_enabled=true, sample_rate=0.2
"Enable heatmaps too, sampled lighter than replay" -> heatmap_enabled=true, heatmap_sample_rate=0.1
"Mask more aggressively and exclude the payment form from recordings" -> mask_level="strict", block_selector=".payment-form"
"Give this site a public share link" -> share_id="lha-public-dashboard"
"Turn off the public link" -> share_id=""
Inputs: name, domain, website, share_id, +7 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 48 tools
Every tool targets a distinct resource+action pair, and potentially confusing pairs are explicitly cross-referenced (e.g. umami_get_goal vs umami_create_goal, umami_reset_website vs umami_delete_website, umami_list_saved_reports vs umami_list_segments_cohorts). Descriptions consistently explain when to prefer one tool over an overlapping alternative, so an agent can reliably select the right one.
The dominant umami_<verb>_<noun> pattern in snake_case is followed by the vast majority of tools (list/get/create/update/delete/reset/join/add/remove). Minor deviations exist: umami_traffic_report lacks a verb, and umami_api_get reverses the pattern to noun_verb, but these are isolated and still readable.
48 tools is heavy and pushes well beyond the 15-25 range where a tool set starts to feel bloated. However, the surface genuinely spans websites, teams, users, core analytics, replays, derived analytics, and persisted reports, so most tools earn their place; the count is defensible but will strain agent navigation.
The domain is covered impressively: full CRUD for websites/teams/users, comprehensive analytics querying, replay inspection, computed conversion/funnel/journey/retention/revenue analytics, and persistence for goals, funnels, segments, and cohorts, plus a read-only API fallback. Notable gaps remain: websites cannot be moved between teams (yet umami_delete_team tells you to reassign them first), and saved reports/segments/cohorts have no update path.
Maintenance
Related MCP Connectors
Privacy-first web analytics. Query pageviews, referrers, trends, and AI insights.
Ask your website analytics in plain language and set up funnels, features and dashboards.
Privacy-first product analytics. Your agent sets up tracking and answers questions about traffic.
Privacy-first, cookie-free web analytics. Read stats and manage sites from your AI.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server for Umami Analytics that provides read-only tools to query website stats, events, sessions, reports, and more, enabling natural language analytics queries.12 npm3MIT
- AlicenseAqualityDmaintenanceA read-only MCP server for Umami analytics, enabling natural language queries of website stats, traffic trends, events, sessions, and analytics reports.1310 npm1Elastic 2.0
- AlicenseNot gradedqualityDmaintenanceA read-only Model Context Protocol server for self-hosted Umami analytics. Enables querying website analytics data such as pageviews, visitors, and metrics through natural language.1MIT
- AlicenseNot gradedqualityBmaintenanceExposes Umami analytics (Cloud or self-hosted) as read-only tools for querying website stats, pageviews, metrics, and active visitors.4,000 npmMIT