MCP

Available since v3.4.0

Umami provides an official Model Context Protocol (MCP) server. It lets MCP clients such as Claude, ChatGPT, and Cursor query your analytics so you can ask questions about traffic, events, funnels, and retention in natural language.

This page answers three questions: how to connect, which questions the server can answer, and what it cannot do.

How it works#

• Read-only. Every tool retrieves data. No tool can change settings, create websites, or delete data.
• Same permissions as the API. Each tool calls the Umami API, so it respects the website and team permissions of the API key you connect with. The MCP server never accesses the database directly.
• Your assistant does the reasoning. Umami supplies the tools and the data. The AI application you connect decides which tools to call and writes the answer, and query results are returned to that application.

Requirements#

You also need an MCP client that supports a remote Streamable HTTP server with a bearer token or custom headers, or one that can run a local stdio server.

Connect to Umami Cloud#

See Cloud MCP for the Cloud endpoint, authentication headers, and client configuration.

Connect to a self-hosted instance#

Step 1: Enable the endpoint#

MCP is disabled by default on self-hosted instances. Set the following environment variable and restart Umami:

MCP_ENABLED=1

For Docker Compose deployments, add MCP_ENABLED=1 to the umami service environment and run docker compose up -d to recreate the container.

Step 2: Create an API key#

Create an API key from your profile menu: select Settings, open API keys, and click Create key. Save the complete key, including its umami_ prefix, when it is shown; it is only displayed once. Browser login tokens are not accepted by the remote endpoint.

Step 3: Configure your MCP client#

Your MCP endpoint is the public URL of your Umami instance followed by /mcp. If your instance uses a base path, include it in the endpoint, for example https://your-umami.example.com/umami/mcp.

Add a remote server that points to this endpoint and sends the key as a bearer token:

{
  "mcpServers": {
    "umami": {
      "url": "https://your-umami.example.com/mcp",
      "headers": {
        "Authorization": "Bearer umami_<your-api-key>"
      }
    }
  }
}

The exact configuration screen and format vary by client. Keep the API key private: the analytics returned by MCP are shared with the AI application to answer your questions.

Step 4: Test the connection#

Ask your assistant: "Show my websites." It should call list_websites and return the websites the key owner can access.

Run the server locally#

If your client only supports local stdio servers, run the @umami/mcp package with npx:

{
  "mcpServers": {
    "umami": {
      "command": "npx",
      "args": ["-y", "@umami/mcp"],
      "env": {
        "UMAMI_URL": "https://your-umami.example.com",
        "UMAMI_API_TOKEN": "umami_<your-api-key>"
      }
    }
  }
}

This configuration connects to Umami's API rather than the remote /mcp endpoint. Do not include /api in UMAMI_URL.

Tools#

Dates use ISO 8601. Results that return individual events or sessions are paginated and have a maximum page size.

Example prompts#

Each prompt maps to one or more of the tools above.

Interpreting results#

• Answers are only as complete as your tracking. Event, revenue, and performance questions depend on what your website records, and funnel, goal, and annotation questions depend on what you have saved.
• Ask the assistant to state the website, date range, and filters it used. This makes it easier to check an answer against the matching report in Umami.
• Results that return individual events or sessions are paginated. For large date ranges, ask for a narrower range or a specific breakdown instead of every row.

Limitations#

• The tools are read-only. The server cannot create or edit websites, funnels, goals, segments, boards, or any other setting.
• Tool coverage is the list above. Session replay recordings, heatmaps, and boards are not available through MCP.
• On Umami Cloud, requests are subject to the same subscription requirements and rate limits as the Cloud API.
• The server does not include an AI model. The quality of an answer depends on the assistant you connect.

Official and community projects#

The server described here is maintained by Umami in the main repository and published as @umami/mcp. Any other MCP server for Umami is a community project. Community servers are not maintained by Umami and may expose different tools or require different credentials.

Revoking access#

Access is tied to the API key. To disconnect an AI tool, delete the key under Settings → API keys.