umami-mcp
This MCP server lets you interact with Umami Analytics v3 for website management, analytics reporting, event collection, user/team administration, and health/auth checks.
Manage websites: list, get, create, update, delete, reset, transfer ownership, get reports, active visitors, realtime data, and date ranges.
Query analytics: stats, pageviews, metrics, events, event series, sessions, session activity, session properties, weekly sessions, and event/session data breakdowns.
Send analytics data: send individual custom events/pageviews and batch multiple events.
Work with saved reports: list, get, create, update, delete, and run funnel, retention, UTM, goals, insights, revenue, journey, and attribution reports.
Administer users: list, create, get, update, delete users; inspect user websites, usage, and teams; manage current user profile, websites, teams, and password.
Administer teams: list, create, get, update, delete, join teams; manage team members and team websites.
Use public/auth endpoints: resolve shared website data, verify authentication, and check server heartbeat.
Provides full-coverage integration for the Umami Analytics API v2, allowing users to manage websites, query analytics statistics and metrics, send custom tracking events, generate reports, and perform administrative tasks for users and teams.
English | 한국어
umami-mcp
Model Context Protocol server for the Umami Analytics v3 API. It supports self-hosted username/password or API-key authentication and Umami Cloud API keys, and exposes analytics, collection, administration, and v3 feature families such as boards, links, pixels, segments, session replay, shares, exports, performance, and revenue.
This version intentionally does not claim every private Umami route. Its tools track the documented API, including Umami 3.4 API-key authentication. Report tools use the legacy report contracts that Umami 3.4 continues to support.
Requirements
Node.js 20 or newer, matching the MCP SDK's installed runtime dependencies
Umami v3.3-compatible self-hosted instance (3.4+ for API keys, session-property segments and annotations), or Umami Cloud with the corresponding routes enabled
Related MCP server: Umami MCP Server
Installation
npm install -g @mikusnuz/umami-mcpOr run it directly:
npx -y @mikusnuz/umami-mcpConfiguration
Self-hosted
{
"mcpServers": {
"umami": {
"command": "npx",
"args": ["-y", "@mikusnuz/umami-mcp"],
"env": {
"UMAMI_URL": "https://analytics.example.com",
"UMAMI_USERNAME": "admin",
"UMAMI_PASSWORD": "your-password"
}
}
}
}UMAMI_URL is the instance origin. A trailing /api is accepted, but is not
required.
On Umami 3.4+, create an API key under Settings → API keys and replace
UMAMI_USERNAME and UMAMI_PASSWORD with UMAMI_API_KEY. Set
UMAMI_MODE to self-hosted to select the deployment mode explicitly.
Umami Cloud
{
"mcpServers": {
"umami": {
"command": "npx",
"args": ["-y", "@mikusnuz/umami-mcp"],
"env": {
"UMAMI_API_KEY": "your-cloud-api-key"
}
}
}
}Cloud management calls default to https://api.umami.is/v1; tool paths are
translated from self-hosted /api/... paths to Cloud /v1/... paths. Set
UMAMI_URL to https://api.umami.is/v1/us or
https://api.umami.is/v1/eu when an explicit Cloud region is required.
For a Cloud API proxy on another hostname, also set UMAMI_MODE to cloud.
Environment variables
Variable | When required | Description |
| Optional |
|
| Self-hosted | Instance origin; optional for Cloud |
| Without a self-hosted API key | Login username |
| Without a self-hosted API key | Login password |
| Cloud; optional for self-hosted 3.4+ | Bearer API key |
| Optional | Separate host for public collection/share/heartbeat/recorder routes |
For Cloud, the collector defaults to https://cloud.umami.is. For self-hosted
Umami it defaults to UMAMI_URL.
An API key without UMAMI_URL, or a URL on api.umami.is, selects Cloud.
Any other configured URL selects self-hosted mode, even when using an API key.
Authentication and public routes
Management and analytics tools send a bearer token. The client logs in to a self-hosted instance lazily and caches the returned JWT when using a password. API keys are sent directly as the bearer credential on both deployment types.
The public collection routes do not require credentials:
send_event,send_identify,send_performancebatch_events(raw JSON array, up to 500 items)heartbeat,get_share,get_recorder_config
If self-hosted login reports that two-factor authentication is required, call
complete_two_factor_login with a current TOTP or backup code, then retry the
original tool. Setup and policy tools are also exposed for self-hosted Umami.
Umami Cloud does not expose /me/password, /users, or /users/* through an
API key. Those tools are for self-hosted instances.
Tool groups
Area | Representative tools |
Websites |
|
Analytics |
|
Event/session data | event values, fields, properties, values, session activity |
Collection | event/pageview, identify, performance, raw batch, link/pixel events |
Reports | saved-report CRUD and |
Boards | list, CRUD, clone, and team boards |
Links and pixels | list, CRUD, charts, and collection events |
Segments | segment/cohort list and CRUD |
Annotations (3.4+) |
|
Replay | recorder config, replay list/detail, saved replays, session replays |
Shares and export | public share resolution, managed website shares, update/delete, CSV ZIP export |
Revenue | stats, chart, metrics, and revenue sessions |
Users and teams | current admin-user and team membership/transfer routes |
2FA | login completion, enrollment, disable, and admin enforcement policies |
Realtime |
|
Use MCP tools/list for the complete, machine-readable list and schemas.
Important v3 contract details
A pageview is sent as
{ "type": "event" }with no eventname; the oldpageviewtype is no longer valid./api/batchreceives the event objects as a raw array, not{ "events": [...] }. The tool returns Umami'sprocessed,errors, and per-itemdetailsfields and marks partial failures as an MCP error result.Collector calls set a stable non-bot
User-Agentheader as required by Umami;send_eventand batch items may also supply the visitor'suserAgentand trusted server-sideipin the payload.Analytics URL filters and page metrics use
path; the oldurlmetric was removed. Host aggregation useshostname.Additional
filtersare preserved even when the corresponding named option is omitted. An explicitly supplied named option takes precedence overfilters.Segment creation and updates support
filters,sessionPropertyFilters,match,dateRange, andaction. Session-property data types are 1=string, 2=number, 3=boolean, 4=date, 5=array. Cohorts do not support session-property filters. Unknown nested fields are rejected rather than silently discarded.Annotations require Umami 3.4+ and website edit permission for writes. Supply an ISO date or timestamp, a 1–500 character note, and optionally
allDay(defaulttrue). Updates replace all three fields; list date filters require bothstartAtandendAtin milliseconds. An older server may return 404.Supported time units are
minute,hour,day,month, andyear.get_event_seriesandget_sessions_weeklyrequire an IANA timezone.list_reportsrequireswebsiteId; report execution sends{ websiteId, type, filters, parameters }.Team website membership is changed through
transfer_website; the removed team-website POST/DELETE routes are not exposed.
Development
npm install
npm testnpm test builds the TypeScript server, checks Cloud/self-hosted URL and auth
behavior, verifies raw public batch requests and the 2FA login flow, and
validates key MCP schemas.
Official references
License
MIT
Available Tools
133 toolsadd_team_userC
Add a user to a team
Inputs: role (required), teamId (required), userId (required).
batch_eventsA
Send multiple events or pageviews in a single batch request
Inputs: events (required).
cancel_two_factor_setupB
Cancel pending self-hosted Umami 2FA setup
Inputs: no named parameters.
clone_boardC
Clone an Umami board
Inputs: boardId (required), name, parameters, description.
complete_two_factor_loginA
Complete a pending self-hosted Umami login after a tool reports that 2FA is required
Inputs: code (required), method (required).
confirm_two_factor_setupB
Confirm self-hosted Umami 2FA setup and receive one-time backup codes
Inputs: token (required).
create_annotationC
Add a dated note to a website's charts (Umami 3.4+)
Inputs: date (required), note (required), websiteId (required), allDay.
create_boardC
Create an Umami board
Inputs: name (required), type (required), teamId, parameters, +1 more.
create_linkC
Create a tracked link
Inputs: url (required), name (required), slug (required), teamId.
create_pixelC
Create a tracking pixel
Inputs: name (required), slug (required), teamId.
create_reportC
Create and save a new report
Inputs: name (required), type (required), websiteId (required), parameters (required), +1 more.
create_segmentC
Create a saved segment or cohort
Inputs: name (required), type (required), websiteId (required), parameters (required).
create_teamC
Create a new team
Inputs: name (required).
create_userB
Create a new user (admin only)
Inputs: role (required), password (required), username (required).
create_websiteC
Create a new website to track in Umami
Inputs: name (required), domain (required), teamId, shareId.
delete_annotationC
Delete a website annotation (Umami 3.4+)
Inputs: websiteId (required), annotationId (required).
delete_boardC
Delete an Umami board
Inputs: boardId (required).
delete_linkC
Delete a tracked link
Inputs: linkId (required).
delete_pixelC
Delete a tracking pixel
Inputs: pixelId (required).
delete_reportC
Delete a saved report
Inputs: reportId (required).
delete_segmentC
Delete a saved segment or cohort
Inputs: segmentId (required), websiteId (required).
delete_sessionC
Delete one session (self-hosted relational storage only)
Inputs: sessionId (required), websiteId (required).
delete_teamC
Delete a team
Inputs: teamId (required).
delete_userB
Delete a user (admin only)
Inputs: userId (required).
delete_websiteB
Delete a website from Umami
Inputs: websiteId (required).
disable_two_factorC
Disable self-hosted Umami 2FA when policy permits
Inputs: token (required), password (required).
export_websiteB
Export website analytics as a base64-encoded ZIP of CSV files
Inputs: endAt (required), startAt (required), websiteId (required), page, +1 more.
get_active_visitorsB
Get the number of currently active visitors on a website
Inputs: websiteId (required).
get_annotationC
Get a website annotation (Umami 3.4+)
Inputs: websiteId (required), annotationId (required).
get_boardC
Get an Umami board
Inputs: boardId (required).
get_daterangeB
Get the date range of available data for a website
Inputs: websiteId (required).
get_event_data_by_idB
Get the custom data attached to one event
Inputs: eventId (required), websiteId (required).
get_event_data_eventsC
Get event data events (custom event names and counts) for a website
Inputs: endAt (required), startAt (required), websiteId (required), event, +1 more.
get_event_data_fieldsB
Get event data fields (property keys and their data types) for a website
Inputs: endAt (required), startAt (required), websiteId (required), filters, +1 more.
get_event_data_propertiesB
Get custom-event property names and their data types for a website
Inputs: endAt (required), startAt (required), websiteId (required), filters.
get_event_data_statsC
Get event data statistics (summary counts) for a website
Inputs: endAt (required), startAt (required), websiteId (required), event, +1 more.
get_event_data_valuesC
Get event data values (aggregated counts for a specific property) for a website
Inputs: endAt (required), startAt (required), websiteId (required), propertyName (required), +3 more.
get_eventsC
List event rows for a website with current Umami v3 filters and pagination
Inputs: endAt (required), startAt (required), websiteId (required), page, +6 more.
get_event_seriesC
Get event metrics over time (event series data) for a website
Inputs: endAt (required), startAt (required), timezone (required), websiteId (required), +5 more.
get_event_valuesC
Get event or session property values for a website
Inputs: type (required), endAt (required), startAt (required), websiteId (required), +2 more.
get_linkC
Get a tracked link
Inputs: linkId (required).
get_link_chartsC
Get chart data for up to 20 tracked links
Inputs: linkIds (required), endAt, startAt, timezone.
get_meA
Get the currently authenticated user's profile information
Inputs: no named parameters.
get_metricsC
Get aggregated metrics for a website (e.g. top pages, browsers, countries, devices, OS, events)
Inputs: type (required), endAt (required), startAt (required), websiteId (required), +6 more.
get_my_teamsA
Get the list of teams the current user belongs to
Inputs: page, orderBy, pageSize, sortDescending.
get_my_websitesC
Get the list of websites belonging to the current user
Inputs: page, orderBy, pageSize, includeTeams, +1 more.
get_pageviewsC
Get pageview and session counts over time for a website
Inputs: endAt (required), startAt (required), websiteId (required), path, +4 more.
get_pixelC
Get a tracking pixel
Inputs: pixelId (required).
get_pixel_chartsC
Get chart data for up to 20 tracking pixels
Inputs: pixelIds (required), endAt, startAt, timezone.
get_realtimeB
Get real-time data for a website (last 30 minutes). Returns current visitors, active URLs, referrers, countries, and events.
Inputs: websiteId (required), path, unit, event, +3 more.
get_recorder_configC
Get public session-replay and heatmap recorder configuration
Inputs: websiteId (required).
get_replayC
Get reconstructed events for one session replay
Inputs: replayId (required), websiteId (required), until, chunkIndex, +1 more.
get_replay_saved_statusC
Check whether one session replay is saved
Inputs: replayId (required), websiteId (required).
get_reportB
Get details of a specific saved report
Inputs: reportId (required).
get_revenue_chartC
Get revenue chart data
Inputs: endAt (required), startAt (required), currency (required), websiteId (required), +4 more.
get_revenue_metricsC
Get revenue metrics by dimension
Inputs: type (required), endAt (required), startAt (required), currency (required), +5 more.
get_revenue_sessionsC
List sessions with revenue data
Inputs: endAt (required), startAt (required), currency (required), websiteId (required), +7 more.
get_revenue_statsC
Get revenue summary and comparison
Inputs: endAt (required), startAt (required), currency (required), websiteId (required), +4 more.
get_segmentC
Get a saved segment or cohort
Inputs: segmentId (required), websiteId (required).
get_sessionC
Get details of a specific session
Inputs: sessionId (required), websiteId (required).
get_session_activityA
Get activity log for a specific session (pages visited, events fired)
Inputs: endAt (required), startAt (required), sessionId (required), websiteId (required), +1 more.
get_session_data_propertiesC
Get session data property names and their data types for a website
Inputs: endAt (required), startAt (required), websiteId (required), filters, +1 more.
get_session_data_valuesC
Get session data values (aggregated counts for session properties) for a website
Inputs: endAt (required), startAt (required), websiteId (required), filters, +2 more.
get_session_propertiesC
Get custom properties attached to a specific session
Inputs: sessionId (required), websiteId (required).
get_sessionsC
Get session data for a website
Inputs: endAt (required), startAt (required), websiteId (required), page, +7 more.
get_session_statsB
Get summarized session statistics for a website (total sessions, unique visitors, etc.)
Inputs: endAt (required), startAt (required), websiteId (required), path, +2 more.
get_sessions_weeklyC
Get weekly session data for a website
Inputs: endAt (required), startAt (required), timezone (required), websiteId (required), +1 more.
get_statsB
Get summary statistics for a website (pageviews, visitors, visits, bounces, totaltime)
Inputs: endAt (required), startAt (required), websiteId (required), path, +5 more.
get_teamC
Get details of a specific team
Inputs: teamId (required).
get_team_userC
Get details of a specific team member
Inputs: teamId (required), userId (required).
get_two_factor_statusB
Get self-hosted Umami 2FA status
Inputs: no named parameters.
get_userB
Get details of a specific user (admin only)
Inputs: userId (required).
get_user_teamsB
Get the list of teams a user belongs to (admin only)
Inputs: userId (required), page, orderBy, pageSize, +1 more.
get_user_two_factor_statusA
Get a user's 2FA enrollment status (self-hosted admin only)
Inputs: userId (required).
get_user_websitesB
Get the list of websites a user has access to (admin only)
Inputs: userId (required), page, search, orderBy, +3 more.
get_websiteA
Get details of a specific website by ID
Inputs: websiteId (required).
get_website_chartsC
Get chart data for up to 20 websites
Inputs: websiteIds (required), endAt, startAt, timezone.
get_website_reportsB
Get all reports associated with a specific website
Inputs: websiteId (required).
heartbeatA
Check if the Umami server is running and healthy
Inputs: no named parameters.
initiate_two_factor_setupB
Start self-hosted Umami 2FA setup
Inputs: no named parameters.
join_teamB
Join a team using an access code
Inputs: accessCode (required).
list_admin_teamsC
List every team (self-hosted admin only)
Inputs: page, search, orderBy, pageSize, +1 more.
list_admin_websitesC
List every website (self-hosted admin only)
Inputs: page, search, orderBy, pageSize, +1 more.
list_annotationsC
List website annotations (Umami 3.4+)
Inputs: websiteId (required), page, endAt, search, +2 more.
list_boardsC
List Umami v3 boards
Inputs: page, search, orderBy, pageSize, +1 more.
list_linksC
List tracked links
Inputs: page, search, orderBy, pageSize, +1 more.
list_pixelsC
List tracking pixels
Inputs: page, search, orderBy, pageSize, +1 more.
list_replaysC
List session replays for a website
Inputs: endAt (required), startAt (required), websiteId (required), page, +4 more.
list_reportsB
List saved reports for a website
Inputs: websiteId (required), page, type, pageSize.
list_saved_replaysC
List saved session replays
Inputs: websiteId (required), page, search, pageSize.
list_segmentsC
List saved segments or cohorts for a website
Inputs: type (required), websiteId (required), search.
list_session_replaysC
List replay recordings linked to one session
Inputs: endAt (required), startAt (required), sessionId (required), websiteId (required), +3 more.
list_team_boardsC
List boards belonging to a team
Inputs: teamId (required), page, search, orderBy, +2 more.
list_team_linksC
List tracked links belonging to a team
Inputs: teamId (required), page, search, orderBy, +2 more.
list_team_pixelsC
List tracking pixels belonging to a team
Inputs: teamId (required), page, search, orderBy, +2 more.
list_teamsC
List all teams
Inputs: page, orderBy, pageSize, sortDescending.
list_team_usersC
List all members of a team
Inputs: teamId (required), page, search, pageSize.
list_team_websitesC
List all websites that belong to a team
Inputs: teamId (required), page, search, orderBy, +2 more.
list_usersA
List all users (admin only)
Inputs: page, search, orderBy, pageSize, +1 more.
list_websitesC
List all websites tracked in Umami
Inputs: page, search, orderBy, pageSize, +2 more.
remove_team_userC
Remove a user from a team
Inputs: teamId (required), userId (required).
reset_user_two_factorA
Reset a user's 2FA enrollment and backup codes (self-hosted admin only)
Inputs: userId (required).
reset_websiteB
Reset a website by removing all its analytics data (irreversible)
Inputs: websiteId (required).
run_reportC
Execute a current Umami v3 report and return its result
Inputs: type (required), websiteId (required), parameters (required), filters.
send_eventB
Send a custom event or pageview to Umami (useful for server-side tracking)
Inputs: url (required), hostname (required), websiteId (required), ip, +10 more.
send_identifyC
Attach custom session data or a distinct ID through Umami's public collection API
Inputs: data (required), websiteId (required), url, hostname, +1 more.
send_link_or_pixel_eventC
Send a public collection event for a tracked link or pixel
Inputs: entityId (required), entityType (required), url, data, +2 more.
send_performanceC
Send Core Web Vitals through Umami's public collection API
Inputs: url (required), hostname (required), websiteId (required), cls, +4 more.
set_global_two_factor_requirementA
Require or stop requiring 2FA globally (self-hosted admin only)
Inputs: required (required).
set_replay_savedC
Save or unsave a session replay (name is used when saving)
Inputs: isSaved (required), replayId (required), websiteId (required), name.
set_team_two_factor_requirementA
Require or stop requiring 2FA for a team (self-hosted owner/manager only)
Inputs: teamId (required), required (required).
set_user_two_factor_requirementA
Require or stop requiring 2FA for a user (self-hosted admin only)
Inputs: userId (required), required (required).
transfer_websiteB
Transfer a website to a user or team using the current Umami transfer endpoint
Inputs: websiteId (required), destinationId (required), destinationType (required).
update_annotationB
Replace an annotation's date, note and all-day flag (Umami 3.4+)
Inputs: date (required), note (required), websiteId (required), annotationId (required), +1 more.
update_boardD
Update an Umami board
Inputs: boardId (required), name, type, parameters, +1 more.
update_linkC
Update a tracked link
Inputs: linkId (required), url, name, slug.
update_my_passwordA
Update the current user's password (self-hosted Umami only; Cloud API keys cannot call this route)
Inputs: newPassword (required), currentPassword (required).
update_pixelC
Update a tracking pixel
Inputs: pixelId (required), name, slug.
update_reportC
Update an existing saved report
Inputs: name (required), type (required), reportId (required), websiteId (required), +2 more.
update_segmentC
Update a saved segment or cohort
Inputs: name (required), type (required), segmentId (required), websiteId (required), +1 more.
update_teamB
Update a team's name or access code
Inputs: teamId (required), name, accessCode.
update_team_userC
Update a team member's role
Inputs: role (required), teamId (required), userId (required).
update_userB
Update a user's username, password, or role (admin only)
Inputs: userId (required), role, password, username.
update_websiteC
Update an existing website's configuration
Inputs: websiteId (required), name, domain, shareId, +1 more.
verify_authB
Verify the current authentication token is valid
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 133 tools
The surface contains many closely related analytics-query tools whose boundaries are hard to infer from names alone: get_stats, get_pageviews, get_metrics, get_events, get_sessions, get_session_stats, get_sessions_weekly, get_event_series, get_realtime, and get_active_visitors all risk misselection. The get_event_data_* family (stats, values, fields, properties, events, by_id) is especially overlapping, and multiple share/replay tools have similarly ambiguous scopes.
Almost all tools use snake_case with a verb-first pattern (list_websites, create_report, delete_segment, get_revenue_stats), which is predictable. There are minor deviations such as heartbeat, batch_events, send_identify, and export_website, but they remain readable and do not undermine the convention.
At 133 tools this is far beyond a well-scoped MCP surface, even for a feature-rich analytics platform. The enormous set mixes core analytics, admin, 2FA, sharing, replays, revenue, and reporting into one overloaded interface, making tool selection difficult.
Coverage is broad and lifecycle-complete for most entities: websites, users, teams, reports, annotations, boards, links, pixels, segments, shares, and replays all have create/get/update/delete-style operations. Minor gaps may exist around some interactions, but the domain surface is substantially covered.
Maintenance
Related MCP Connectors
Read and edit GA4, Search Console and Google Tag Manager from any MCP client. 29 tools.
Hosted MCP server for DataLikers — Instagram & TikTok data API. 51 tools: Instagram user search by demographics (gender/age/race/country/city), profiles, bulk lookup, engagement, posts & reels, comments, hashtags, locations, stories, highlights, music, business accounts, top users; TikTok users, videos, comments, hashtags, playlists and top charts. Streamable HTTP, Bearer API key. Free tier: 100 requests on signup at https://datalikers.com/p/1by27bwg
MCP server for Statsig API - interact with Statsig's feature flags, experiments, and analytics
Marketo MCP server for AI. 130 tools to operate Marketo from Claude, Cursor, or ChatGPT.
Related MCP Servers
- AlicenseCqualityCmaintenanceMCP server exposing Umami analytics (Cloud + self-hosted)5MIT
- AlicenseAqualityDmaintenanceRead-only MCP server for Umami analytics. It talks to the Umami REST API directly over HTTP, supporting self-hosted and cloud setups.88 npmMIT
- 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.24 npm3MIT
- AlicenseAqualityDmaintenanceA security-first MCP server for Umami analytics (Cloud and self-hosted v3) enabling analytics, reporting, and administration with least privilege and credential-safe design.328 npmMIT