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: Umami 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

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

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.