Skip to main content
Glama
umami-mcp

umami-mcp

by mikusnuz

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-mcp

Or run it directly:

npx -y @mikusnuz/umami-mcp

Configuration

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

UMAMI_MODE

Optional

self-hosted or cloud; auto-detected when omitted

UMAMI_URL

Self-hosted

Instance origin; optional for Cloud

UMAMI_USERNAME

Without a self-hosted API key

Login username

UMAMI_PASSWORD

Without a self-hosted API key

Login password

UMAMI_API_KEY

Cloud; optional for self-hosted 3.4+

Bearer API key

UMAMI_COLLECTOR_URL

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_performance

  • batch_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

list_websites, CRUD, reset, transfer to user/team, replay configuration

Analytics

get_stats, get_pageviews, get_metrics, get_events, get_sessions, event series

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 run_report for attribution, breakdown, funnel, goal, heatmap, journey, performance, retention, revenue, and UTM

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+)

list_annotations, get_annotation, create_annotation, update_annotation, delete_annotation

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

get_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 event name; the old pageview type is no longer valid.

  • /api/batch receives the event objects as a raw array, not { "events": [...] }. The tool returns Umami's processed, errors, and per-item details fields and marks partial failures as an MCP error result.

  • Collector calls set a stable non-bot User-Agent header as required by Umami; send_event and batch items may also supply the visitor's userAgent and trusted server-side ip in the payload.

  • Analytics URL filters and page metrics use path; the old url metric was removed. Host aggregation uses hostname.

  • Additional filters are preserved even when the corresponding named option is omitted. An explicitly supplied named option takes precedence over filters.

  • Segment creation and updates support filters, sessionPropertyFilters, match, dateRange, and action. 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 (default true). Updates replace all three fields; list date filters require both startAt and endAt in milliseconds. An older server may return 404.

  • Supported time units are minute, hour, day, month, and year.

  • get_event_series and get_sessions_weekly require an IANA timezone.

  • list_reports requires websiteId; 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 test

npm 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 tools
add_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_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_shareC

Create a share for a website, link, pixel, or board

Inputs: name (required), entityId (required), shareType (required), slug, +1 more.

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.

create_website_shareD

Create a website share

Inputs: name (required), websiteId (required), parameters.

delete_annotationC

Delete a website annotation (Umami 3.4+)

Inputs: websiteId (required), annotationId (required).

delete_boardC

Delete an Umami board

Inputs: boardId (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_shareC

Delete a managed share

Inputs: shareId (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_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_shareA

Resolve a public Umami share by its slug without authentication

Inputs: slug (required).

get_share_by_idC

Get a managed share by internal ID

Inputs: shareId (required).

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_entity_sharesC

List shares for a website, link, pixel, or board

Inputs: entityId (required), entityType (required), page, search, +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_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.

list_website_sharesC

List shares created for a website

Inputs: websiteId (required), page, search, pageSize.

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_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_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_shareC

Update a managed share

Inputs: name (required), slug (required), shareId (required), parameters (required).

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

    C2.4/5.0

    Scored across 133 tools

    Disambiguation2/5

    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.

    Naming Consistency4/5

    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.

    Tool Count1/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Read-only MCP server for Umami analytics. It talks to the Umami REST API directly over HTTP, supporting self-hosted and cloud setups.
      8
      8 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for Umami Analytics that provides read-only tools to query website stats, events, sessions, reports, and more, enabling natural language analytics queries.
      24 npm
      3
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      A security-first MCP server for Umami analytics (Cloud and self-hosted v3) enabling analytics, reporting, and administration with least privilege and credential-safe design.
      32
      8 npm
      MIT