# mikusnuz/umami-mcp [Health: Active]

**Category:** 📊 Monitoring  
**Repository:** https://github.com/mikusnuz/umami-mcp  
**GitHub Stars:** 7  
**npm Downloads (last month):** 733  
**Views:** 2  
**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 tracked websites
- **get_website** — Get website details by ID
- **create_website** — Create a new website
- **update_website** — Update website configuration
- **delete_website** — Delete a website
- **get_active_visitors** — Get current active visitor count
- **reset_website** — Reset all analytics data for a website
- **transfer_website** — Transfer website ownership to another user
- **get_website_reports** — Get all reports for a website
- **get_stats** — Summary statistics (pageviews, visitors, bounce rate, etc.)
- **get_pageviews** — Pageview/session counts over time
- **get_metrics** — Aggregated metrics (top pages, browsers, countries, etc.)
- **get_events** — Event data over time
- **get_sessions** — Session listing with filters
- **get_daterange** — Available data date range
- **get_event_series** — Event metrics over time (event series)
- **get_session_stats** — Summarized session statistics
- **get_sessions_weekly** — Weekly session data
- **get_session** — Session details
- **get_session_activity** — Session activity log
- **get_session_properties** — Session custom properties
- **get_session_data_properties** — Session data property names and types
- **get_session_data_values** — Session data aggregated values
- **send_event** — Send custom events/pageviews (server-side tracking)
- **get_event_values** — Event/session property values
- **get_event_data_events** — Event data events (custom event names and counts)
- **get_event_data_fields** — Event data fields (property keys and types)
- **get_event_data_values** — Event data values (aggregated counts for a property)
- **get_event_data_stats** — Event data statistics summary
- **batch_events** — Send multiple events in a single batch request
- **list_reports** — List saved reports
- **get_report** — Get report details
- **create_report** — Create and save a report
- **update_report** — Update an existing report
- **delete_report** — Delete a saved report
- **run_report** — Execute a report (funnel, retention, utm, goals, insights, revenue, journey, attribution)
- **list_users** — List all users
- **create_user** — Create a new user (username, password, role)
- **get_user** — Get user details
- **update_user** — Update user (username, password, or role)
- **delete_user** — Delete a user
- **get_user_websites** — List websites a user has access to
- **get_user_usage** — Get usage statistics for a user
- **get_user_teams** — List teams a user belongs to
- **list_teams** — List all teams
- **create_team** — Create a new team
- **get_team** — Get team details
- **update_team** — Update team name
- **delete_team** — Delete a team
- **join_team** — Join a team using an access code
- **list_team_users** — List team members
- **get_team_user** — Get details of a specific team member
- **add_team_user** — Add a user to a team
- **update_team_user** — Update a team member's role
- **remove_team_user** — Remove a user from a team
- **list_team_websites** — List websites belonging to a team
- **add_team_website** — Add a website to a team
- **remove_team_website** — Remove a website from a team
- **get_me** — Get current authenticated user profile
- **get_my_websites** — List current user's websites
- **get_my_teams** — List current user's teams
- **update_my_password** — Update current user's password
- **verify_auth** — Verify authentication token is valid
- **get_share** — Get shared website data by share ID
- **heartbeat** — Check if Umami server is healthy
- **get_realtime** — Real-time data for last 30 minutes (visitors, URLs, referrers, countries, events)

## 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_URL": "",
      "UMAMI_USERNAME": "",
      "UMAMI_PASSWORD": "",
      "UMAMI_API_KEY": ""
    }
  }
}
```

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

## Documentation & README

**English** | [한국어](https://github.com/mikusnuz/umami-mcp/blob/HEAD/README.ko.md)

# umami-mcp

Model Context Protocol server for the current **Umami Analytics v3.3 API**.
It supports self-hosted username/password authentication and Umami Cloud API
keys, and exposes analytics, collection, administration, and newer 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 and the public v3.3.1 server contracts.

## Requirements

- Node.js 18 or newer
- Umami v3.3-compatible self-hosted instance, or an Umami Cloud API key

## Installation

```bash
npm install -g @mikusnuz/umami-mcp
```

Or run it directly:

```bash
npx -y @mikusnuz/umami-mcp
```

## Configuration

### Self-hosted

```json
{
  "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.

### Umami Cloud

```json
{
  "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.

### Environment variables

| Variable | When required | Description |
|---|---|---|
| `UMAMI_URL` | Self-hosted | Instance origin; optional for Cloud |
| `UMAMI_USERNAME` | Self-hosted | Login username |
| `UMAMI_PASSWORD` | Self-hosted | Login password |
| `UMAMI_API_KEY` | Cloud | 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`.

## 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; Cloud uses the API key
as the bearer credential.

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 |
| 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`.
- 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

```bash
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

- [Umami API overview](https://docs.umami.is/docs/api)
- [Authentication](https://docs.umami.is/docs/api/authentication)
- [Cloud API keys](https://docs.umami.is/docs/cloud/api-key)
- [Sending statistics](https://docs.umami.is/docs/api/sending-stats)
- [Website statistics](https://docs.umami.is/docs/api/website-stats)
- [Reports](https://docs.umami.is/docs/api/reports)
- [Cloud/API changelog](https://docs.umami.is/docs/cloud/changelog)
- [Umami v3.3.1 server source](https://github.com/umami-software/umami/tree/v3.3.1)

## License

MIT