What can you do with this server?

Query and explore Umami web analytics through an MCP client, from aggregate stats to individual user journeys and page content. * List websites and IDs. * Get overview metrics: pageviews, visitors, visits, bounces, total time over a date range. * Break down visitors by URL/path, referrer, browser, OS, device, country, or event. * Retrieve pageview/session time series by hour, day, or month with timezone support. * Check real-time active visitor count. * Find session IDs in a range, optionally filtered by event. * Inspect a session's full tracking timeline/user journey. * Semantically search many user journeys for relevant behavior moments ([rag] extra). * Fetch raw HTML of a live page. * Capture rendered page screenshots ([screenshot] extra). * Assemble a dashboard via the Create Dashboard prompt. * Work with Umami Cloud or self-hosted using API key or username/password. Note: README lists get_event_data, but the supplied server schema does not include it.

Which integrations are available for this server?

Provides tools for accessing Umami web analytics data, including website stats, pageviews, metrics, active visitors, and user journey tracking.

How do I use umami-mcp-server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@umami-mcp-server What were my top pages last week?" 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

by MurkyPuma

Overview Schema Source Related Servers Discussions Admin

Python

Local

Umami Analytics MCP Server

Talk to your Umami web analytics in plain English. Let Claude pull your stats, spot trends, trace user journeys, and build dashboards, no SQL, no clicking through charts.

This is a Model Context Protocol server that connects Umami to any MCP client (Claude Desktop, Cursor, and others). Ask a question, and the model picks the right analytics calls, reads the data, and answers, then you can keep going: drill in, compare ranges, or have it assemble a full dashboard.

It is a modernized, dependency-light rewrite of jakeyShakey/umami_mcp_server: FastMCP, an async HTTP client, a tiny core install, optional heavy features, and a test suite. See CHANGELOG.md for the full diff in spirit.

See it in action

You:    Which pages drove the most traffic last week, and where did those visitors come from?

Claude: (get_websites → get_website_metrics type=url → get_website_metrics type=referrer)
        Your top pages last week were /pricing, /blog/getting-started, and /. Most of
        that traffic came from Google, then a Hacker News thread, then direct visits.
        Want me to break the /pricing visitors down by country or device?

You:    Yeah, and show me what a typical /pricing visitor did before they left.

Claude: (get_website_metrics type=country → get_session_ids → get_tracking_data)
        ...

The model drives the tools. You just ask.

Related MCP server: BigQuery MCP Server

Why you might want this

Plain-language analytics. No dashboards to navigate or queries to write.
Lightweight by default. The core install is just mcp, httpx, and python-dotenv. No torch, no headless browser unless you opt in.
Async and non-blocking. The Umami client is built on httpx.AsyncClient.
Works with self-hosted or Umami Cloud. API-key or username/password auth.
Honest about quality. Pure-function test suite plus CI (ruff + pytest) on Python 3.10 to 3.13.

Tools

Tool	What it returns	Requires
`get_websites`	Your websites and their ids (start here)	core
`get_website_stats`	Pageviews, visitors, visits, bounces, total time	core
`get_website_metrics`	Breakdown by path, referrer, browser, os, device, country, language, hostname, or event; optional hostname filter	core
`get_event_data`	Custom event properties, and one property's values with counts	core
`get_pageview_series`	Pageviews/sessions time series (hour/day/month)	core
`get_active_visitors`	Current real-time visitor count	core
`get_session_ids`	Unique session ids in a range, optionally filtered by event	core
`get_tracking_data`	Full activity timeline for one session	core
`get_html`	Raw HTML of a live page (HTTP GET, no JS)	core
`get_docs`	Semantic search across many user journeys	`[rag]`
`get_screenshot`	Rendered screenshot of a live page	`[screenshot]`

There is also a Create Dashboard prompt that walks the model through building a full dashboard for a website and date range. Date arguments accept YYYY-MM-DD or YYYY-MM-DD HH:MM:SS and are interpreted as UTC.

Quick start

Requires Python 3.10+.

1. Install

pip install "git+https://github.com/MurkyPuma/umami-mcp-server.git"

2. Add it to Claude Desktop

Edit your config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "umami": {
      "command": "umami-mcp-server",
      "env": {
        "UMAMI_API_URL": "https://cloud.umami.is",
        "UMAMI_API_KEY": "your-api-key"
      }
    }
  }
}

3. Restart Claude Desktop and ask it something like "List my websites and last week's visitors." The tools appear under the tools (hammer) icon.

If umami-mcp-server is not on Claude Desktop's PATH, use the absolute path to the console script (for example /path/to/.venv/bin/umami-mcp-server), or set "command" to your Python interpreter with "args": ["-m", "umami_mcp"].

Optional features (extras)

The heavy, situational tools are opt-in so the default install stays small.

# Semantic journey search (get_docs). Pulls torch-sized wheels.
pip install "umami-mcp-server[rag] @ git+https://github.com/MurkyPuma/umami-mcp-server.git"

# Rendered screenshots (get_screenshot). Then install the browser once.
pip install "umami-mcp-server[screenshot] @ git+https://github.com/MurkyPuma/umami-mcp-server.git"
playwright install chromium

# Everything
pip install "umami-mcp-server[all] @ git+https://github.com/MurkyPuma/umami-mcp-server.git"

Without an extra, its tool still appears but returns a one-line install hint instead of failing, so nothing breaks.

Configuration

Set these as environment variables (in the MCP client config) or in a local .env (see .env.example).

Variable	Required	Description
`UMAMI_API_URL`	yes	Your Umami base URL, for example `https://cloud.umami.is`
`UMAMI_API_KEY`	one of	API key, sent as `x-umami-api-key` (Umami Cloud / newer self-hosted)
`UMAMI_USERNAME` / `UMAMI_PASSWORD`	one of	Credentials exchanged for a bearer token
`UMAMI_TEAM_ID`	no	If set, `get_websites` lists that team's sites; otherwise yours
`UMAMI_TIMEOUT`	no	Per-request timeout in seconds (default 30)

Provide either UMAMI_API_KEY, or both UMAMI_USERNAME and UMAMI_PASSWORD.

Development

git clone https://github.com/MurkyPuma/umami-mcp-server.git
cd umami-mcp-server
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

pytest          # run the tests
ruff check .    # lint

No live Umami is needed to test: the async client is exercised with httpx.MockTransport, and the RAG tests cover the pure chunking/ranking helpers (the embedding model is not loaded in CI).

src/umami_mcp/
  config.py    # env -> Settings (pure, no side effects)
  dates.py     # date string -> UTC unix millis (pure)
  client.py    # async httpx Umami client (auth, retry, endpoints)
  web.py       # get_html via httpx; optional Playwright screenshot
  rag.py       # optional semantic search (sentence-transformers + numpy)
  server.py    # FastMCP tools + Create Dashboard prompt
  __main__.py  # entry point

Contributing

Issues and PRs are welcome. The codebase is small and the tests are fast; a good first contribution is adding a tool for an Umami endpoint that is not covered yet.

If this saves you a trip to the Umami dashboard, a ⭐ helps other people find it.

Credits

Original concept and first implementation by jakeyShakey. Licensed under MIT.

Available Tools

10 tools

get_active_visitorsA

Get the number of visitors currently active on a website (real-time).

Args: website_id: The website id (from get_websites).

Inputs: website_id (required). Returns: result

get_docsA

Semantic search over many user journeys to surface the most relevant moments.

Pulls every session for the range (optionally filtered to selected_event), then returns only the journey chunks most relevant to user_question -- letting you analyze behavior across many users without overflowing the context window.

Requires the optional 'rag' extra; without it, this returns install instructions.

Args: user_question: What you want to learn (used for the similarity search). website_id: The website id (from get_websites). start_at: Range start (UTC). end_at: Range end (UTC). selected_event: Optional event name to filter sessions by.

Inputs: user_question (required), website_id (required), start_at (required), end_at (required), +1 more. Returns: result

get_htmlA

Fetch the raw HTML of a live web page (HTTP GET, no JavaScript execution).

Useful for giving the model the structure/markup of a page you're analyzing.

Args: url: Full URL including scheme, e.g. 'https://example.com/pricing'.

Inputs: url (required). Returns: result

get_pageview_seriesA

Get a pageviews-and-sessions time series, bucketed by hour, day, or month.

Use 'hour' for short ranges (1-7 days), 'day' for medium ranges, 'month' for long ranges.

Args: website_id: The website id (from get_websites). start_at: Range start (UTC). end_at: Range end (UTC). unit: Bucket size: hour, day, or month. timezone: IANA timezone for bucketing, e.g. 'UTC' or 'Europe/London'.

Inputs: website_id (required), start_at (required), end_at (required), unit (required), +1 more. Returns: result

get_screenshotA

Capture a rendered screenshot of a live web page.

Requires the optional 'screenshot' extra (Playwright); without it, this returns install instructions instead of an image.

Args: url: Full URL including scheme, e.g. 'https://example.com'.

Inputs: url (required).

get_session_idsA

Get the unique session ids active in a range, optionally filtered to an event.

Use this to find sessions to inspect with get_tracking_data, not to count unique visitors (use get_website_stats for counts). Pass event_name to keep only sessions that fired that event, or omit it for all sessions.

Args: website_id: The website id (from get_websites). start_at: Range start (UTC). end_at: Range end (UTC). event_name: Optional event name to filter by (e.g. 'checkout_completed').

Inputs: website_id (required), start_at (required), end_at (required), event_name. Returns: result

get_tracking_dataA

Get the full activity timeline (user journey) for one session.

Args: website_id: The website id (from get_websites). start_at: Range start (UTC). end_at: Range end (UTC). session_id: The session to inspect (from get_session_ids).

Inputs: website_id (required), start_at (required), end_at (required), session_id (required). Returns: result

get_website_metricsA

Get a breakdown of visitors by a dimension over a date range.

type selects the dimension: url (pages), referrer (traffic sources), browser, os, device, country, or event (tally of tracked events).

Args: website_id: The website id (from get_websites). start_at: Range start (UTC). end_at: Range end (UTC). type: One of url, referrer, browser, os, device, country, event.

Inputs: website_id (required), start_at (required), end_at (required), type (required). Returns: result

get_websitesA

List the websites in your Umami account, with their ids, names, and domains.

Takes no arguments. Use the returned id for the other tools. If a team id is configured the team's websites are returned; otherwise your personal websites.

Inputs: no named parameters. Returns: result

get_website_statsA

Get overview metrics for a website over a date range.

Returns pageviews, unique visitors, visits, bounces, and total time. If you get no data, double-check the date range before assuming there is none.

Args: website_id: The website id (from get_websites). start_at: Range start, 'YYYY-MM-DD' or 'YYYY-MM-DD HH:MM:SS' (UTC). end_at: Range end, same formats (a bare date includes the whole day).

Inputs: website_id (required), start_at (required), end_at (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.2/5.0

Scored 2026-06-20 02:20 across 10 tools

Disambiguation5/5

All tools have clearly distinct purposes: real-time active visitors, semantic journey search, raw HTML, pageview time series, screenshots, session IDs, session details, metric breakdowns, website listing, and aggregated stats. No overlapping functionality.

Naming Consistency5/5

Every tool uses the consistent 'get_' prefix followed by a descriptive noun phrase in snake_case (e.g., get_active_visitors, get_pageview_series). Even the slightly vague 'get_docs' follows the pattern.

Tool Count5/5

10 tools is well-scoped for an analytics MCP server. It covers core analytics (stats, series, breakdowns, sessions) plus useful extras (HTML, screenshot, RAG search) without being overwhelming.

Completeness4/5

The set provides comprehensive read-only coverage of Umami analytics: listing websites, retrieving stats, time series, dimensional breakdowns, session data, and active visitors. Missing write operations and some advanced analytics (e.g., retention, funnel) are minor gaps for a query-focused server.

Resources

Related MCP Connectors

GSCPAP - Google Search Console, GA4, PageSpeed Insights & live SERPs MCPB
com.gscpap
Google Search Console, GA4 and PageSpeed MCP server for Claude, ChatGPT and Cursor. Free, hosted.
Search Monitoring Marketing
4212
https://mcp.gscpap.com/mcp
Clamp Analytics
sh.clamp
Clamp Analytics MCP server: traffic, revenue, funnels, cohorts, errors, and search, for AI agents.
Monitoring Search
2
https://api.clamp.sh/mcp
mcpulseA
com.getmcpulse
Analytics for MCP servers. Query your tool calls, first-call success, retries and schema cost.
Data Visualization Monitoring Observability
1
https://api.getmcpulse.com/mcp
AgentCat
com.agentcat
Analytics and debugging for your MCP server — explore usage and sessions, then root-cause errors.
Monitoring Observability
2
https://mcp.agentcat.com/mcp

Related MCP Servers

Umami MCP Server
Monitoring Observability
Mzaxd
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.
Updated 6 months ago (2026-04-30 02:05 UTC)
8
8 npm
MIT
BigQuery MCP Server
Cloud Platforms Databases Search
Suganthan-Mohanadasan
A
license
A
quality
C
maintenance
An MCP server for BigQuery that lets Claude answer questions about your search and analytics data, providing real analysis with verdicts and recommendations, not just raw query results.
Updated 3 months ago (2026-08-27 11:05 UTC)
32
44
Apache 2.0
umami-mcp-server
Monitoring Observability
frontedu
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.
Updated 4 months ago (2026-07-18 15:19 UTC)
24 npm
3
MIT
@byterover/umami-mcp
Monitoring Observability
campfirein
A
license
A
quality
D
maintenance
A read-only MCP server for Umami analytics, enabling natural language queries of website stats, traffic trends, events, sessions, and analytics reports.
Updated 4 months ago (2026-07-05 02:56 UTC)
13
10 npm
1
Elastic 2.0