# mikusnuz/umami-mcp [Health: Active]

**Category:** 📊 Monitoring  
**Repository:** https://github.com/mikusnuz/umami-mcp  
**GitHub Stars:** 8  
**npm Downloads (last month):** 282  
**Views:** 5  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mikusnuz-umami-mcp

## Description
Full-coverage MCP server for Umami Analytics API v2 — 66 tools for websites, stats, sessions, events, reports, users, teams, and realtime monitoring.

## Tools
Capabilities this server exposes over MCP:

- **list_websites** — List all websites tracked in Umami
- **get_website** — Get details of a specific website by ID
- **create_website** — Create a new website to track in Umami
- **update_website** — Update an existing website's configuration
- **delete_website** — Delete a website from Umami
- **get_active_visitors** — Get the number of currently active visitors on a website
- **reset_website** — Reset a website by removing all its analytics data (irreversible)
- **transfer_website** — Transfer website ownership to another user
- **get_website_reports** — Get all reports associated with a specific website
- **get_stats** — Get summary statistics for a website (pageviews, visitors, visits, bounces, totaltime)
- **get_pageviews** — Get pageview and session counts over time for a website
- **get_metrics** — Get aggregated metrics for a website (e.g. top pages, browsers, countries, devices, OS, events)
- **get_events** — Get event data for a website over time
- **get_sessions** — Get session data for a website
- **get_daterange** — Get the date range of available data for a website
- **get_event_series** — Get event metrics over time (event series data) for a website
- **get_session_stats** — Get summarized session statistics for a website (total sessions, unique visitors, etc.)
- **get_sessions_weekly** — Get weekly session data for a website
- **get_session** — Get details of a specific session
- **get_session_activity** — Get activity log for a specific session (pages visited, events fired)
- **get_session_properties** — Get custom properties attached to a specific session
- **get_session_data_properties** — Get session data property names and their data types for a website
- **get_session_data_values** — Get session data values (aggregated counts for session properties) for a website
- **send_event** — Send a custom event or pageview to Umami (useful for server-side tracking)
- **get_event_values** — Get event or session property values for a website
- **get_event_data_events** — Get event data events (custom event names and counts) for a website
- **get_event_data_fields** — Get event data fields (property keys and their data types) for a website
- **get_event_data_values** — Get event data values (aggregated counts for a specific property) for a website
- **get_event_data_stats** — Get event data statistics (summary counts) for a website
- **batch_events** — Send multiple events or pageviews in a single batch request
- **list_reports** — List all saved reports
- **get_report** — Get details of a specific saved report
- **create_report** — Create and save a new report
- **update_report** — Update an existing saved report
- **delete_report** — Delete a saved report
- **run_report** — Execute a report by type and get results (funnel, retention, utm, goals, insights, revenue, journey, attribution)
- **list_users** — List all users (admin only)
- **create_user** — Create a new user (admin only)
- **get_user** — Get details of a specific user (admin only)
- **update_user** — Update a user's username, password, or role (admin only)
- **delete_user** — Delete a user (admin only)
- **get_user_websites** — Get the list of websites a user has access to (admin only)
- **get_user_usage** — Get usage statistics for a specific user (admin only)
- **get_user_teams** — Get the list of teams a user belongs to (admin only)
- **list_teams** — List all teams
- **create_team** — Create a new team
- **get_team** — Get details of a specific team
- **update_team** — Update a team's name
- **delete_team** — Delete a team
- **join_team** — Join a team using an access code
- **list_team_users** — List all members of a team
- **add_team_user** — Add a user to a team
- **update_team_user** — Update a team member's role
- **get_team_user** — Get details of a specific team member
- **remove_team_user** — Remove a user from a team
- **list_team_websites** — List all websites that belong to a team
- **add_team_website** — Add a website to a team
- **remove_team_website** — Remove a website from a team
- **get_realtime** — Get real-time data for a website (last 30 minutes). Returns current visitors, active URLs, referrers, countries, and events.
- **get_me** — Get the currently authenticated user's profile information
- **get_my_websites** — Get the list of websites belonging to the current user
- **get_my_teams** — Get the list of teams the current user belongs to
- **update_my_password** — Update the current user's password
- **verify_auth** — Verify the current authentication token is valid
- **get_share** — Get shared website data by share ID (public access, no auth required for the share itself)
- **heartbeat** — Check if the Umami server is running and healthy

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "umami-mcp": {
    "command": "npx",
    "args": ["-y","@mikusnuz/umami-mcp"],
    "env": {
      "UMAMI_MODE": "",
      "UMAMI_URL": "",
      "UMAMI_USERNAME": "",
      "UMAMI_PASSWORD": "",
      "UMAMI_API_KEY": "",
      "UMAMI_COLLECTOR_URL": ""
    }
  }
}
```

**Requires environment variables:** `UMAMI_MODE`, `UMAMI_URL`, `UMAMI_USERNAME`, `UMAMI_PASSWORD`, `UMAMI_API_KEY`, `UMAMI_COLLECTOR_URL` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What mikusnuz/umami-mcp does

mikusnuz/umami-mcp exposes the documented Umami Analytics v3 API through the Model Context Protocol. It covers analytics queries, website administration, event collection, reports, boards, links, pixels, segments, annotations, session replay, shares, exports, performance data, revenue, users, teams, two-factor authentication flows, and realtime information.

The server supports Umami instances compatible with v3.3 and newer, with API-key features requiring Umami 3.4 or later. It can also connect to Umami Cloud when the relevant routes are available. Use MCP `tools/list` to inspect the complete tool inventory and input schemas.

## How it works

Management and analytics requests use a bearer token. With self-hosted username and password authentication, the server logs in only when needed and caches the resulting JWT. API keys are passed directly as bearer credentials. Public collection and selected public routes do not require authentication.

Self-hosted requests use the configured Umami instance URL. Cloud requests default to the Umami Cloud API and translate self-hosted-style paths to Cloud paths. A separate collector URL can be configured for public collection, sharing, heartbeat, and recorder endpoints.

The server handles Umami-specific API contracts, including raw-array batch requests, the v3 event shape for pageviews, `path`-based URL metrics, and timezone requirements for selected time-series tools. Batch collection accepts up to 500 items and reports processing results, errors, and per-item details.

## Setup and configuration

Use Node.js 20 or newer. Install the package globally with `npm install -g @mikusnuz/umami-mcp`, or launch it with `npx -y @mikusnuz/umami-mcp` from an MCP client's stdio configuration.

For self-hosted Umami, set `UMAMI_URL` and either `UMAMI_USERNAME` plus `UMAMI_PASSWORD`, or `UMAMI_API_KEY` on Umami 3.4 and later. `UMAMI_MODE=self-hosted` can explicitly select that deployment type. For Umami Cloud, provide `UMAMI_API_KEY`; `UMAMI_URL` is optional unless a specific region or proxy is needed. Set `UMAMI_MODE=cloud` for a Cloud proxy on another hostname.

`UMAMI_COLLECTOR_URL` optionally selects a separate host for public collection and related routes. Cloud defaults this collector to `https://cloud.umami.is`; self-hosted deployments default to `UMAMI_URL`.

## Tools and capabilities

- List, create, update, delete, reset, and transfer websites.
- Query statistics, pageviews, metrics, events, sessions, event series, session properties, and date ranges.
- Inspect individual session details, activity, and custom properties.
- Send events and pageviews, identify visitors, send performance data, and submit raw event batches.
- Manage and execute reports, including attribution, funnel, goal, heatmap, journey, retention, revenue, and UTM report types.
- Work with boards, links, pixels, segments, cohorts, annotations, shares, exports, replay data, and revenue analytics.
- Manage supported users, teams, two-factor authentication flows, and realtime data.

## Limitations and notes

Umami Cloud API keys do not expose the `/me/password`, `/users`, or `/users/*` routes; those user tools apply to self-hosted instances. Annotation writes require Umami 3.4 or later and website edit permission. Event series and weekly session queries require an IANA timezone. Team website membership changes use `transfer_website`, and removed team-website routes are not exposed.

The project is licensed under MIT.

_Full upstream README: https://allmcps.com/mcp/mikusnuz-umami-mcp/readme_