Skip to main content
Glama
Umami MCP Server

Umami MCP Server

by lukasschmit

Umami MCP Server

An MCP server for Umami Analytics — works with both Umami Cloud and self-hosted instances.

Zero dependencies. No cloning, no install steps — just point your MCP client at it.

Why?

Existing Umami MCP servers either don't support Umami Cloud (which uses API key auth, not username/password) or are broken and bloated (torch, faiss, sentence-transformers for… analytics?).

This server talks to the Umami API and exposes 5 tools over MCP. Pure Python, zero dependencies.

Related MCP server: Plausible Analytics MCP Server

Tools

Tool

Description

get_websites

List all tracked websites

get_stats

Summary stats: pageviews, visitors, visits, bounces, totaltime (seconds)

get_pageviews

Time-series pageview/session data (unit: minute/hour/day/month/year; timezone: IANA, e.g. UTC)

get_metrics

Breakdown by type: path/url/entry/exit/referrer/domain/title/query/event/tag/hostname/browser/os/device/screen/language/country/region/city/channel

get_active

Number of currently active visitors (last 5 minutes)

Quick Start

1. Get your credentials

Umami Cloud: Go to Settings → API Keys in your Umami Cloud dashboard and create an API key.

Self-hosted: Use the username and password you log in with.

2. Add to your MCP client

No cloning required — uvx fetches and runs it directly from GitHub.

Requires uv. Install with: curl -LsSf https://astral.sh/uv/install.sh | sh

Claude Desktop / Claude Code

Add to your MCP config (~/.claude.json, Claude Desktop settings, etc.):

Umami Cloud:

{
  "mcpServers": {
    "umami": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/lukasschmit/umami-mcp", "umami-mcp"],
      "env": {
        "UMAMI_URL": "https://api.umami.is",
        "UMAMI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Self-hosted:

{
  "mcpServers": {
    "umami": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/lukasschmit/umami-mcp", "umami-mcp"],
      "env": {
        "UMAMI_URL": "https://your-umami-instance.com",
        "UMAMI_USERNAME": "admin",
        "UMAMI_PASSWORD": "your_password"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root (or global settings):

{
  "mcpServers": {
    "umami": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/lukasschmit/umami-mcp", "umami-mcp"],
      "env": {
        "UMAMI_URL": "https://api.umami.is",
        "UMAMI_API_KEY": "your_api_key_here"
      }
    }
  }
}

VS Code (Copilot)

Add to your VS Code settings.json:

{
  "mcp": {
    "servers": {
      "umami": {
        "command": "uvx",
        "args": ["--from", "git+https://github.com/lukasschmit/umami-mcp", "umami-mcp"],
        "env": {
          "UMAMI_URL": "https://api.umami.is",
          "UMAMI_API_KEY": "your_api_key_here"
        }
      }
    }
  }
}

BoltAI

Go to Settings → MCP Servers → Add Server, then enter:

  • Command: uvx

  • Arguments: --from git+https://github.com/lukasschmit/umami-mcp umami-mcp

  • Environment Variables:

    • UMAMI_URL = https://api.umami.is

    • UMAMI_API_KEY = your_api_key_here

Environment Variables

Variable

Required

Description

UMAMI_URL

Self-hosted: Yes, Cloud: Optional

Base URL — defaults to https://api.umami.is in Cloud mode

UMAMI_API_KEY

Cloud

API key from Umami Cloud dashboard

UMAMI_USERNAME

Self-hosted

Login username

UMAMI_PASSWORD

Self-hosted

Login password

UMAMI_CF_ACCESS_CLIENT_ID

Optional

Cloudflare Access service token client ID (for protected self-hosted APIs)

UMAMI_CF_ACCESS_CLIENT_SECRET

Optional

Cloudflare Access service token secret

UMAMI_USER_AGENT

Optional

Custom User-Agent for outbound requests (default: umami-mcp/1.0)

UMAMI_DEBUG

Optional

Set to 1/true to log outbound request URLs to stderr for debugging

Set either UMAMI_API_KEY (Cloud) or both UMAMI_USERNAME + UMAMI_PASSWORD (self-hosted). The server auto-detects which mode to use. For convenience, UMAMI_URL may include /v1 (Cloud) or /api (self-hosted); suffixes are normalized automatically.

If your self-hosted Umami is behind Cloudflare Access, set both UMAMI_CF_ACCESS_CLIENT_ID and UMAMI_CF_ACCESS_CLIENT_SECRET so machine-to-machine MCP calls can pass Access checks.

get_metrics accepts both type="path" and type="url" for compatibility across Umami versions. startAt and endAt accept Unix-millisecond integers or numeric strings from MCP clients. For time-based tools, you can use range instead of raw timestamps: last_24h, last_7d, last_30d, this_month, last_month. compare supports prev (previous period, same length) and yoy (year-over-year).

Usage Examples

Once connected, you can ask your AI assistant things like:

  • "What are my top pages this week?"

  • "Show me visitor trends for the last 30 days"

  • "Which countries are my visitors from?"

  • "How many people are on my site right now?"

  • "Compare this month's traffic to last month"

The assistant will call the appropriate tools with the right parameters.

How It Works

The server implements the Model Context Protocol over stdio (JSON-RPC, one JSON object per line). When an MCP client starts it, the server:

  1. Reads JSON-RPC messages from stdin

  2. Handles initialize, tools/list, and tools/call methods

  3. Makes authenticated HTTP requests to the Umami API

  4. Returns results as JSON text content

No background processes, no polling, no state beyond the auth token.

License

MIT

Available Tools

5 tools
get_activeB

Get the number of currently active visitors on a website (last 5 minutes).

Inputs: websiteId (required).

get_metricsC

Get a breakdown of metrics by a given dimension (url, referrer, browser, os, device, country, event, etc.) for a website.

Inputs: websiteId (required), startAt (required), endAt (required), type (required), +16 more.

get_pageviewsC

Get time-series pageview and session data for a website, bucketed by the chosen time unit.

Inputs: websiteId (required), startAt (required), endAt (required), unit (required), +16 more.

get_statsB

Get summary statistics (pageviews, visitors, visits, bounces, totaltime) for a website over a date range. Timestamps are Unix milliseconds.

Inputs: websiteId (required), startAt (required), endAt (required), compare, +14 more.

get_websitesC

List all tracked websites in your Umami account.

Inputs: search, page, pageSize, includeTeams.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: get_active focuses on real-time visitor counts, get_metrics provides dimensional breakdowns, get_pageviews offers time-series data, get_stats gives summary statistics, and get_websites lists available websites. There is no overlap or ambiguity in their functions.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with 'get_' as the prefix (e.g., get_active, get_metrics, get_pageviews, get_stats, get_websites). This uniformity makes the set predictable and easy to understand.

    Tool Count5/5

    With 5 tools, this server is well-scoped for analytics purposes, covering key aspects like real-time data, metrics, time-series, summaries, and website listing. Each tool earns its place without feeling excessive or insufficient.

    Completeness4/5

    The toolset provides strong coverage for querying analytics data, including active visitors, detailed metrics, pageviews, stats, and websites. A minor gap is the lack of tools for configuration or management (e.g., adding websites or events), but agents can effectively work with the provided read-only operations.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enhances Claude's capabilities by providing access to website analytics data from Umami, enabling analysis of user behavior, website performance tracking, and data-driven insights generation.
      9
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to query website statistics from Plausible Analytics, providing access to metrics like real-time visitors, traffic trends, and page performance. It supports both Plausible Cloud and self-hosted instances through the Stats API v2.
      6
      42 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Exposes Umami analytics (Cloud or self-hosted) as read-only tools for querying website stats, pageviews, metrics, and active visitors.
      4,000 npm
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables natural-language analytics against Umami, including traffic stats, time series, sessions, custom events, and filtered breakdowns, plus self-hosted admin CRUD for websites, users, and teams, and client onboarding.
      48
      12 npm
      1
      MIT