umami-mcp-server

Ein MCP-Server für Umami Analytics. Schreibgeschützt, funktioniert sowohl mit Umami Cloud als auch mit selbst gehosteten Instanzen und spricht in Zeiträumen wie last_month und Websitenamen wie example.com statt in Epochen-Millisekunden und UUIDs.

Fünfundzwanzig Werkzeuge decken Website-Entdeckung, Traffic-Statistiken, Zeitreihen, Ranglisten-Aufschlüsselungen, benutzerdefinierte Ereignisse, einzelne Sitzungen, einen vollständigen Bericht mit einem einzigen Aufruf, vollständige Admin-CRUD-Funktionen für Websites/Benutzer/Teams, ein zusammengesetztes Client-Onboarding-Werkzeug und eine rohe GET-Hintertür für alles Weitere in der Umami-API ab.

Admin-Werkzeuge (Benutzer, Teams und Websites erstellen; beliebiges löschen) erfordern selbst gehostetes Umami mit einem Admin-Login oder einem Admin-API-Schlüssel. Umami Cloud stellt keine Benutzer- oder Teamverwaltung über die API bereit, deshalb geben diese Werkzeuge eine klare Fehlermeldung zurück, wenn sie auf die Cloud gerichtet werden, statt einer verwirrenden 404.

Installation

npm install
npm run build

Related MCP server: Plausible MCP

Konfiguration

Kopiere .env.example und fülle einen der beiden Authentifizierungspfade aus.

Umami Cloud

Erstelle einen Schlüssel unter Einstellungen, API-Schlüssel.

Selbst gehostet

Beides

Einbinden

Claude Desktop oder Claude Code

Füge zu claude_desktop_config.json hinzu oder führe claude mcp add aus:

{
  "mcpServers": {
    "umami": {
      "command": "node",
      "args": ["/absolute/path/to/umami-mcp-server/dist/index.js"],
      "env": {
        "UMAMI_API_KEY": "your-key",
        "UMAMI_TIMEZONE": "America/New_York",
        "UMAMI_DEFAULT_WEBSITE": "example.com"
      }
    }
  }
}

Für eine selbst gehostete Instanz setze UMAMI_BASE_URL ein und entweder den Schlüssel oder das Benutzername/Passwort-Paar.

MCP Inspector

UMAMI_API_KEY=your-key npm run inspect

Werkzeuge

Analyse (schreibgeschützt)

Admin: Websites (selbst gehostet, Admin-Login oder -Schlüssel)

Admin: Benutzer (selbst gehostet, Admin-Login oder -Schlüssel)

Admin: Teams (selbst gehostet, Admin-Login oder -Schlüssel)

Bereitstellung

Notausstieg

Jedes Datenwerkzeug akzeptiert response_format: json für eine lesbare Zusammenfassung, markdown für das strukturierte Ergebnis. Jedes destruktive Werkzeug (reset, delete, remove) verlangt das Argument confirm-datestype: true; ohne dieses wird der Aufruf abgelehnt, und es gibt keinen zusätzlichen Bestätigungssschritt. Betrachte dieses Argument also als Punkt ohne Wiederkehr.

Datumsbereiche

Übergib range in einer der folgenden Formen:

• Relativ: 30m, 24h, 7d, 4w, 3mo, 1y

• Benannt: today, yesterday, this_week, last_week, this_month, last_month, this_yearcyt, mtd, ytd, all_time

Oder übergib start_date und end_date als YYYY-MM-DD, vollständigen ISO-8601-Timestamp oder Epochen-Millisekunden. Explizite Datumsangaben haben Vorrang vor range. Tagesgrenzen richten sich nach UMAMI_TIMEZONE oder zu einem timezone-Argument pro Anruf.

Filter

Die meisten Werkzeuge akzeptieren ein filters-Objekt, das die Abfrage segmentiert:

{ "country": "US", "device": "mobile", "path": "/pricing" }

Unterstützte Schlüssel: path, referrer, title, query, browser, os, device, country, region, city, language, hostname, tag, event, distinctId, utmSource, utmMedium, utmCampaign, utmContent, utmTerm, segment, cohort.

Aufschlüsselungs-Dimensionen

Für umami_get_metrics und das breakdowns-Argument von umami_traffic_report: path, entry, exit, title, query, referrer, channel, domain, country, region, city, browser, os, device, language, screen, event, hostname, tag, distinctId.

Beispiele

Stell deine Fragen nach dem Verbinden einfach auf natürlich:

• „Wie lief die Website letzten Monat im Vergleich zum Monat davor?“ → umami_get_stats mit range=last_month

• „Gib mir die komplette Analyse-Übersicht für die letzten 30 Tage“ → umami_traffic_report

• „Wie ist die Absprungrate verschiedener Landingpages?“ → besser: „Welche Landingpage hat die höchste Abbruchrate?“ → umami_get_metrics mit type=entry, expanded=true

• „Wie viele Kontaktformular-Submissions diese Woche?“ → umami_get_events_series mit event=contact-form-submit

• „Zeig mir die top Pages für mobile Besucher aus Florida“ → umami_get_metrics mit type=path, filters={ device: "mobile", region: "US-FL" }

• „Was hat diese Session tatsächlich auf der Website gemacht?“ → umami_list_sessions, dann umami_get_session

• „Richte Tracking für den neuen Kunden ein, ein eigenes Team dafür und füge nur Jordan hinzu“ → umami_onboard_client mit website_name, domain, team_name, grant_user_id

• „Lösche die Testdaten, bevor diese Website live geht“ → umami_reset_website mit confirm=true

Design-Hinweise

• Website-Auflösung. Das website-Argument jedes Tools akzeptiert eine UUID, einen Namen oder eine Domain. Namen und Domains werden gegen eine 60 Sekunden lang zwischengespeicherte Website-Liste abgeglichen, wobei bei Mehrdeutigkeit ein expliziter Fehler ausgegeben wird, statt stillschweigend falsch zu raten. Das Erstellen, Aktualisieren oder Löschen einer Website aktualisiert diesen Cache sofort.

• Vollständige Replay-/Heatmap-Konfiguration, nicht nur Schalter. umami_update_website legt jedes Feld offen, das Umamis replayConfig akzeptiert: Aktivierungsflags, unabhängige Sampling-Raten für Replay bzw. Heatmaps, PII-Maskierungsstufe, Block-Selektor und maximale Aufzeichnungsdauer. Umamis eigene Dokumentation verwendet uneinheitliche Einheiten für maxDuration (ein Beispiel impliziert Millisekunden, ein anderes Sekunden); statt zu raten liest umami_get_recorder_config denselben öffentlichen Endpoint, den der Tracker selbst aufruft, sodass man den tatsächlichen Wert nach dem Speichern bestätigen kann, anstatt einem der Dokumentationsbeispiele zu vertrauen*.

• Abgeleitete Metriken. Umami liefert rohe bounces- und totaltime-Zählwerte. Absprungrate, Seitenaufrufe pro Besuch und durchschnittliche Besuchsdauer werden hier mitberechnet, damit jede Antwort direkt lesbar ist*.

• Teilweiser Fehlschlag. umami_traffic_report führt seine Aufschlüsselungen parallel aus und verwirft jede Dimension, die die Instanz nicht unterstützt, wobei die ausgelassenen Dimensionen benannt werden, statt den gesamten Bericht scheitern zu lassen. Das ist wichtig, weil die Unterstützung von Dimensionen je nach Umami-Version variiert*.

• Destroy-Operationen sind opt-in und werden nicht zweimal bestätigt. umami_reset_website, umami_delete_website, umami_delete_user, umami_remove_team_user und umami_delete_team verlangen alle ein literales confirm: true-Argument und schlagen andernfalls fehl. Es gibt keine separate "Sind Sie sicher?"-Rückfrage: Der Tool-Aufruf selbst ist die Bestätigung, daher sollte ein Agent (oder eine Person) confirm: true nur dann übergeben, wenn es auch ernst gemeint ist*.

• umami_onboard_client ist Best-Effort, nicht transaktional. Umamis API unterstützt keinerlei mehrstufige Transaktionen. Falls die Team-Erstellung gelingt, aber der Website-Schritt scheitert, bleibt das Team bestehen, und die Fehlermeldung sagt das ausdrücklich, mit einem Hinweis darauf, wo als Nächstes zu prüfen ist, statt stillschweigend zurückzurollen oder den partiellen Zustand zu verbergen*.

• Notausgang. umami_api_get ist bewusst rein als GET ausgelegt, getrennt von den obigen Admin-Tools. Es kann nichts erstellen, ändern, zurückgesetzen oder löschen*.

• Antwortgröße. Antworten sind auf 25.000 Zeichen begrenzt, mit einem Hinweis auf limit, offset oder einen engeren Zeitraum.

Tests

npm test

test/smoke.mjs fährt eine simulierte Umami-API sowie einen echten MCP-Client über stdio auf und übt die Analytics-Tools samt ihrer Fehlerpfade. test/auth.mjs deckt den Login-Austausch auf selbst gehosteten Systemen sowie die Aktualisierung des Tokens, die abläuft, wenn ein gecachter Bearer-Token veraltetet ist. test/admin.mjs deckt Website-/Benutzer-/Team-CRUD, Teammitgliedschaft, das kombinierte Onboarding-Tool und die Bestätigung ab, dass jedes destruktive Tool sich ohne confirm=true weigert zu laufen.

Geprüft gegen

Umami-v3-API-Referenz, Stand August 2026: /websites, /websites/:id, /websites/:id/stats, /pageviews, /metrics, /metrics/expanded, /events/series, /active, /daterange, /sessions, /sessions/:id, /sessions/:id/activity, /websites/:id/reset, /users, /admin/users, /users/:id, /users/:id/websites, /users/:id/teams, /teams, /teams/join, /teams/:id, /teams/:id/users, /teams/:id/users/:userId, /teams/:id/websites. Cloud-Anfragen gehen an https://api.umami.is/v1 mit einem Bearer-Token; selbst gehostete Anfragen gehen an {base}/api*. Endpoints für Benutzer- und Teamverwaltung existieren nur auf selbst gehosteten Instanzen.

Lizenz

MIT