umami_mcp_server

The Umami Analytics MCP Server connects Claude to your Umami analytics data, enabling natural language access to website metrics, user journeys, and page-level insights. It exposes a set of tools that let Claude fetch website lists, view key metrics, drill into time-series data, inspect active visitors, and retrieve session-specific activity. You can also run semantic searches across user journeys, capture screenshots, and analyze HTML structure for deeper context. Use these tools to build dashboards, diagnose performance issues, compare pages or campaigns, and generate data-driven recommendations directly from Claude.

Prerequisites:

• Python with uv installed (pip install uv)
• Access to a configured Umami instance and credentials for UMAMI_API_URL, UMAMI_USERNAME, UMAMI_PASSWORD, and UMAMI_TEAM_ID
• Claude Desktop configured to connect to the MCP server (optional but recommended)

Installation steps:

1. Clone the MCP server repository to your local machine.
2. Create and activate a Python environment (recommended):

python -m venv venv
source venv/bin/activate  # on macOS/Linux
venv\Scripts\activate  # on Windows

3. Install dependencies (adjust if a requirements file is provided in your repo):

pip install -r requirements.txt

4. Ensure the server is discoverable by your MCP manager. Use the uv IPC flow shown in your config:

uv --directory /path/to/analytics_service run analytics-service

5. Populate the environment variables (UMAMI_API_URL, UMAMI_USERNAME, UMAMI_PASSWORD, UMAMI_TEAM_ID) in your shell or in the MCP config as shown in the example.
6. Start Claude Desktop and verify the analytics_service MCP server appears with 10 tools available once initialized.

Tips and notes:

• The environment variables UMAMI_API_URL, UMAMI_USERNAME, UMAMI_PASSWORD, and UMAMI_TEAM_ID are required for Umami access. Keep credentials secure and avoid committing them to public files.
• The get_docs tool uses semantic search over user journeys and chunked embeddings to reduce token usage; this helps when asking about long journeys or complex flows.
• get_screenshot and get_html rely on the Crawl4AI crawler; ensure network access to target websites and be mindful of rate limits.
• If you modify prompts or tool usage, update the server’s prompt definitions in src/analytics_service/server.py accordingly.
• If you encounter initialization delays, allow Claude Desktop a few minutes for the MCP server to install packages and initialise.