home / mcp / umami mcp server

Umami MCP Server

Exposes Umami Cloud analytics via MCP tools to query websites, stats, pageviews, metrics, and active visitors.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "alurith-umami-mcp-server": {
      "command": "uvx",
      "args": [
        "run",
        "umami-mcp-server"
      ],
      "env": {
        "UMAMI_API_KEY": "YOUR_UMAMI_CLOUD_API_KEY",
        "UMAMI_API_BASE": "https://api.umami.is/v1",
        "UMAMI_PASSWORD": "YOUR_PASSWORD",
        "UMAMI_USERNAME": "YOUR_USERNAME"
      }
    }
  }
}

You can run the Umami MCP Server to access Umami Cloud analytics through practical MCP tools that let you list websites, fetch visitor stats, view page views over time, and more. This server exposes a focused set of endpoints you can use via your MCP client to monitor and analyze your Umami data efficiently.

How to use

Launch the MCP server in your environment and connect to it from your MCP client. You will access a collection of tools designed to retrieve and summarize Umami Cloud analytics, including listing your websites, pulling visitor statistics, viewing page traffic trends, and inspecting metrics such as browsers, countries, and devices. Use the client to pass the appropriate tool name and parameters, and the server will return structured results suitable for dashboards or automation.

How to install

Prerequisites you need to prepare before installing: Python 3.13 or later and the uv runtime. You also require the MCP runner tool you will use to start the server locally.

1) Install the MCP runner (example commonly used is uvx). 2) Ensure you have your Umami Cloud API key or credentials for a self-hosted setup, as described in the environment configuration. 3) Start the server using the MCP runner with the appropriate command.

# Install or ensure uvx is available in your environment
# Example: install globally if needed
npm i -g uvx

# Run the Umami MCP Server locally
uvx run umami-mcp-server

Additional notes

Configuration revolves around providing authentication and API base details so the MCP server can reach Umami Cloud or your self-hosted instance. You can customize how the server authenticates by supplying one of the supported combinations of credentials, as detailed in the environment variables. When running locally, you can place these values in your environment or in your OpenCode configuration as shown in examples.

Environment variables you may configure include UMAMI_API_KEY for Umami Cloud access, UMAMI_USERNAME and UMAMI_PASSWORD for self-hosted setups, and UMAMI_API_BASE to point to your API root (defaults to https://api.umami.is/v1 when not specified). Ensure you provide at least one valid authentication method.

{
  "mcp": {
    "umami": {
      "type": "local",
      "command": ["uvx", "run", "umami-mcp-server"],
      "environment": {
        "UMAMI_API_KEY": "YOUR_UMAMI_CLOUD_API_KEY",
        "UMAMI_API_BASE": "https://api.umami.is/v1"
      },
      "enabled": true
    }
  }
}

Available tools

get_websites

List all your websites managed in Umami Cloud or the self-hosted instance.

get_stats

Retrieve visitor statistics for a specified time range and filters.

get_pageviews

View page traffic trends over time for selected pages or websites.

get_metrics

Obtain detailed metrics such as browsers, countries, devices, and other audience dimensions.

get_active

Get the current number of active visitors on your sites.