Umami MCP-Server

Schreibgeschützter MCP-Server für Umami-Analysen. Er kommuniziert direkt über HTTP mit der Umami-REST-API, unterstützt primär selbst gehostetes Umami und funktioniert auch mit Umami-Cloud-API-Schlüsseln.

Dieses Repository wurde so konzipiert, dass übergeordnete Agenten Analysedaten abrufen können, ohne jedes Mal die Umami-Dokumentation lesen zu müssen. Keine Browser-Automatisierung, kein DOM-Scraping, keine Schreibvorgänge.

Funktionen

• Schreibgeschützte MCP-Tools für die gängigsten Umami-Analyseabfragen

• Zwei Authentifizierungsmodi:

  • UMAMI_API_KEY

  • UMAMI_USERNAME + UMAMI_PASSWORD

• Zwischenspeicherung des Bearer-Tokens im Arbeitsspeicher bei selbst gehosteten Instanzen

• Automatische erneute Anmeldung und ein Wiederholungsversuch bei 401 im Benutzername/Passwort-Modus

• Akzeptiert sowohl ISO-Zeitzeichenfolgen als auch Zeitstempel in Millisekunden

• Gemeinsame Filterbehandlung für Statistiken, Seitenaufrufe, Aufschlüsselungen und Ereignisserien

• Strenges TypeScript mit kleinen, wartbaren Modulen

• Klare, strukturierte Tool-Ausgabe und explizite Fehlerkategorien

Anforderungen

• Node.js >= 20

• pnpm >= 10

Installation

Über npm:

npm install -g umami-analytics-mcp

Oder ohne Installation ausführen:

npx -y umami-analytics-mcp

Für die lokale Entwicklung in diesem Repository:

pnpm install

Konfiguration

Erstellen Sie eine .env-Datei basierend auf .env.example.

cp .env.example .env

Füllen Sie eine der folgenden Authentifizierungsoptionen aus:

1. API-Schlüssel-Modus

UMAMI_API_URL=https://api.umami.is/v1
UMAMI_API_KEY=your-api-key
UMAMI_DEFAULT_TIMEZONE=Asia/Shanghai

2. Modus für selbst gehosteten Benutzername/Passwort

UMAMI_API_URL=https://umami.example.com/api
UMAMI_USERNAME=admin
UMAMI_PASSWORD=secret
UMAMI_DEFAULT_TIMEZONE=Asia/Shanghai

Hinweise:

• UMAMI_API_URL sollte auf die API-Basis zeigen, nicht nur auf den Ursprung der Website.

• Wenn sowohl UMAMI_API_KEY als auch Benutzername/Passwort festgelegt sind, hat UMAMI_API_KEY Vorrang.

• UMAMI_DEFAULT_TIMEZONE wird verwendet, wenn ein Tool eine Zeitzone unterstützt und Sie diese weglassen.

Lokal ausführen

Entwicklungsmodus:

pnpm dev

Erstellen und ausführen:

pnpm build
pnpm start

Der Server verwendet den MCP-Stdio-Transport und bleibt daher mit stdin/stdout verbunden, bis der Client die Verbindung trennt.

Bei einer Installation über npm lautet der entsprechende Befehl:

umami-analytics-mcp

Testen

pnpm test
pnpm build

Es gibt auch eine Vorlage für Integrationstests mit der echten API, die standardmäßig übersprungen wird:

UMAMI_INTEGRATION_TEST=1 pnpm test:integration

MCP-Inspektor

Zuerst erstellen:

pnpm build

Starten Sie dann den offiziellen MCP-Inspektor für den erstellten Server:

npx @modelcontextprotocol/inspector node dist/cli.js

Für Hot-Reload während der Entwicklung funktioniert auch:

npx @modelcontextprotocol/inspector pnpm dev

Wenn Sie stattdessen den Pfad des veröffentlichten Pakets testen möchten, verwenden Sie:

npx @modelcontextprotocol/inspector npx -y umami-analytics-mcp

Stellen Sie sicher, dass dem Inspektor-Prozess dieselben Umami-Umgebungsvariablen zur Verfügung stehen.

Empfohlene Smoke-Tests im Inspektor:

1. umami_ping

2. umami_list_websites

3. umami_get_stats

4. umami_get_breakdown

Tools

umami_ping

Überprüft die Konfiguration und Authentifizierung.

Beispiel:

{}

umami_list_websites

Listet zugängliche Websites auf.

Beispiel:

{}

umami_find_website

Fuzzy-Suche nach Website-Name oder Domain.

Beispiel:

{
  "query": "example.com"
}

umami_get_stats

Zusammenfassende Statistiken für eine Website und einen Zeitraum.

Beispiel:

{
  "websiteId": "8f2f8ce2-1234-4567-89ab-0123456789ab",
  "startAt": "2026-04-23T00:00:00+08:00",
  "endAt": "2026-04-23T23:59:59+08:00",
  "filters": {
    "path": "/pricing"
  }
}

umami_get_pageviews

Zeitreihen für Seitenaufrufe und Sitzungen.

Beispiel:

{
  "websiteId": "8f2f8ce2-1234-4567-89ab-0123456789ab",
  "startAt": "2026-04-17T00:00:00+08:00",
  "endAt": "2026-04-23T23:59:59+08:00",
  "unit": "day",
  "compare": "prev",
  "filters": {
    "path": "/blog"
  }
}

umami_get_breakdown

Aufschlüsselungszeilen wie Top-Seiten, Referrer, Länder, Browser, Geräte und mehr.

Beispiel:

{
  "websiteId": "8f2f8ce2-1234-4567-89ab-0123456789ab",
  "startAt": "2026-04-17T00:00:00+08:00",
  "endAt": "2026-04-23T23:59:59+08:00",
  "type": "path",
  "limit": 10,
  "expanded": false
}

umami_get_active

Gibt die aktuelle Anzahl der aktiven Besucher zurück.

Beispiel:

{
  "websiteId": "8f2f8ce2-1234-4567-89ab-0123456789ab"
}

umami_get_events_series

Gibt benutzerdefinierte Ereignisanzahlen im Zeitverlauf zurück.

Beispiel:

{
  "websiteId": "8f2f8ce2-1234-4567-89ab-0123456789ab",
  "startAt": "2026-04-17T00:00:00+08:00",
  "endAt": "2026-04-23T23:59:59+08:00",
  "unit": "day"
}

Gemeinsame Filter

Diese Tools unterstützen dasselbe filters-Objekt:

• path

• referrer

• title

• query

• browser

• os

• device

• country

• region

• city

• hostname

Fehlerbehandlung

Tool-Fehler werden als strukturierte MCP-Tool-Ergebnisse mit folgenden Kategorien zurückgegeben:

• config_missing

• auth_failed

• website_not_found

• umami_http_error

• network_timeout

• network_error

• invalid_input

In jedem Stdio-MCP-Client einbinden

Jeder stdio-basierte MCP-Client kann diesen Server wie folgt ausführen:

• command: npx

• args: ["-y", "umami-analytics-mcp"]

• env: Ihre Umami-Variablen

Beispiel-JSON-Snippet für Clients, die ein mcpServers-Objekt verwenden:

{
  "mcpServers": {
    "umami": {
      "command": "npx",
      "args": ["-y", "umami-analytics-mcp"],
      "env": {
        "UMAMI_API_URL": "https://umami.example.com/api",
        "UMAMI_USERNAME": "admin",
        "UMAMI_PASSWORD": "secret",
        "UMAMI_DEFAULT_TIMEZONE": "Asia/Shanghai"
      }
    }
  }
}

Für einen lokalen, nicht veröffentlichten Checkout können Sie weiterhin direkt auf die erstellte Datei verweisen:

{
  "mcpServers": {
    "umami": {
      "command": "node",
      "args": ["/absolute/path/to/umami-mcp/dist/cli.js"]
    }
  }
}

Auf npm veröffentlichen

Dieses Repository ist jetzt als npm-CLI-Paket strukturiert.

Empfohlener Release-Ablauf:

pnpm test
pnpm build
pnpm pack --dry-run
npm login
pnpm publish

Hinweise:

• Der Paketname ist auf umami-analytics-mcp festgelegt, da umami-mcp auf npm bereits vergeben ist.

• Die aktuelle license ist UNLICENSED als sicherer Platzhalter. Ersetzen Sie diese vor einer echten öffentlichen Open-Source-Veröffentlichung, wenn Sie eine permissive Lizenz wünschen.

• Wenn Sie später unter Ihrem eigenen npm-Scope veröffentlichen, ändern Sie nur das Feld name in der package.json.

Interne Dokumentation

• API-Zusammenfassung, die von diesem Repository verwendet wird: docs/umami-api.md