<div align="center">

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.

</div>

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.

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 url, referrer, browser, os, device, country, or event	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.