Umami MCP Server

Ein Model Context Protocol-Server für Umami Analytics. Fragen Sie Claude, Cursor oder einen beliebigen MCP-Client nach Ihrem Traffic – und lassen Sie ihn Websites erstellen und verwalten – während Ihre Anmeldedaten auf Ihrem eigenen Rechner bleiben.

"Which pages drove the most visitors last month, and where did that traffic come from?"
"Build a funnel from /pricing to /signup to /welcome for the last 30 days."
"Add analytics for my new site blog.example.com and give me the tracking snippet."

Warum es das gibt

Umami hat keinen offiziellen MCP-Server. Es gibt mehrere Community-Versionen, und wenn Sie nur eine breite API-Abdeckung möchten, sollten Sie sich zuerst 0xtlt/umami-mcp ansehen – es kapselt mehr von der API als dieses Projekt. Einige der älteren Server (jakeyShakey, mikusnuz, mittwald, Macawls) wurden gegen die v2-API geschrieben und brechen auf einer modernen Instanz, weil v3 Dinge ohne Aliase umbenannt hat:

Dieser Server existiert für zwei Dinge, die die anderen nicht tun:

1. Vollständige, verifizierte v3-Report-Abdeckung. Alle sieben v3-Report-Typen – Trichter, Retention, Journey, Ziel, Umsatz, Attribution und UTM – wurden gegen eine Live-Umami-3.3.1-Instanz getestet. Der Report-Envelope ist leicht falsch zu machen: Daten kommen in parameters als ISO-8601-Strings, nicht in filters und nicht als die Epochen-Millisekunden, die der Rest der API verwendet. Attribution nimmt first-click / last-click, nicht die camelCase-Schreibweisen, die man vermuten würde.

2. Ein Fähigkeitsmodell statt eines booleschen Werts. Siehe unten.

Related MCP server: Umami MCP Server

Sicherheitsmodell

Ein Analytics-MCP-Server hält eine Anmeldeinformation, die jede Besuchersitzung lesen kann, die Sie je aufgezeichnet haben – und, wenn Sie es zulassen, das Ganze löschen kann. Das Design folgt daraus.

Ihre Anmeldedaten verlassen niemals Ihre Umgebung. Die Konfiguration wird nur aus der Prozessumgebung gelesen. Es gibt keine Telemetrie, kein Phone-Home und kein gehostetes Relay. Der einzige Host, den dieser Server je kontaktiert, ist die von Ihnen gesetzte UMAMI_URL. Wenn Sie ihn selbst hosten, gelangen keine Ihrer Analysedaten jemals an Dritte – einschließlich des Autors dieser Software.

Seien Sie vorsichtig bei jedem Umami-MCP, das einen gehosteten Endpunkt anbietet, den Sie auf Ihre Instanz richten. Selbst gehostetes Umami hat keine API-Schlüssel, daher bedeutet „bequemes Hosting", dass Sie Ihr Admin-Passwort an den Server von jemand anderem mailen.

Least Privilege standardmäßig. Der Server startet im Modus read. Eine Erweiterung ist eine bewusste Handlung:

Zurückgehaltene Tools werden überhaupt nicht registriert, sodass sie nie in der Tool-Liste des Modells erscheinen. Das ist der Teil, der sich von einem READONLY=true-Flag unterscheidet: Ein Tool, das nie beworben wurde, kann nicht durch eine prompt-injizierte Anweisung aufgerufen werden, die in, sagen wir, einer Referrer-URL oder einem Seitentitel in Ihren eigenen Analysedaten versteckt ist. Es gibt keine Laufzeitprüfung, die man vergessen oder umgehen könnte, weil es kein Tool gibt.

Zerstörerische Aktionen benötigen eine getippte Bestätigung, die gegen die Realität geprüft wird. umami_delete_website nimmt ein confirmDomain-Argument, holt den Live-Datensatz und lehnt ab, es sei denn, sie stimmen überein. Ein Modell das nach der falschen Website-UUID greift, erhält einen Fehler, nicht einen gelöschten Datensatz.

Anmeldedaten bleiben außerhalb der Client-Konfiguration. Anstatt Ihr Passwort in ~/.claude.json oder mcp.json zu verlangen, liest der Server es aus einer Datei, die Sie unter ~/.config/umami-mcp/env kontrollieren, und warnt, wenn diese Datei für andere Benutzer lesbar ist. Siehe Anmeldedaten.

Geheimnisse werden aus der Ausgabe entfernt. MCP-Ausgabe fließt in ein Modell und oft in ein Chat-Transkript, das nicht mehr zurückgenommen werden kann. Passwörter, Bearer-Tokens und JWTs werden aus jedem Fehler und jeder Antwort entfernt, bevor sie den Prozess verlassen.

Weigert sich, Anmeldedaten über die Leitung zu leaken. Klartext-HTTP zu einem Remote-Host wird beim Start abgelehnt; es ist nur für localhost erlaubt, für die lokale Entwicklung.

Installation

Drei Möglichkeiten, es auszuführen. Self-Hosting ist die Standard- und die empfohlene Option – die gehostete Instanz existiert, damit Sie es in zwei Minuten ausprobieren können, ohne etwas zu klonen.

Wenn Sie selbst hosten und es in Claude Web verwenden möchten, führen Sie es mit UMAMI_MCP_OAUTH=true hinter Ihrer eigenen Domain aus – dann berührt nichts von Ihnen die Infrastruktur anderer.

1. Gehostete Instanz nutzen (nichts zu installieren)

Fügen Sie in Claude einen benutzerdefinierten Connector hinzu, der auf Folgendes zeigt:

https://umami-mcp.asif.dev/mcp

Sie werden auf einem Zustimmungsbildschirm nach Ihrer eigenen Umami-URL und Ihrem Login gefragt. Siehe Claude Web, Cowork und Claude Code im Web für die Handhabung der Anmeldedaten.

2. Aus dem Quellcode

git clone https://github.com/Asif2BD/umami-mcp.git
cd umami-mcp
npm install && npm run build

Richten Sie dann Anmeldedaten ein und registrieren Sie sie bei Ihrem Client:

claude mcp add umami --scope user -- node "$PWD/dist/index.js"

Erfordert Node 20 oder neuer.

3. Docker

git clone https://github.com/Asif2BD/umami-mcp.git
cd umami-mcp
cp .env.example .env    # then edit .env
docker compose up -d

npm: noch nicht veröffentlicht. Sobald es das ist, wird npx -y @asif2bd/umami-mcp den Clone-and-Build-Schritt oben ersetzen. Bis dahin verwenden Sie Quelle oder Docker.

Anmeldedaten

Selbst gehostetes Umami hat keine API-Schlüssel, daher ist die Anmeldeinformation, die dieser Server hält, ein echtes Kontopasswort. MCP-Clients möchten das normalerweise in ihrer Konfigurations-JSON eingebettet haben – ~/.claude.json, mcp.json und ähnliche – die weit verbreitet lesbar sind, in Issues und Screen-Shares eingefügt werden und von einigen Clients zwischen Maschinen synchronisiert werden.

Dieser Server liest Anmeldedaten also aus einer Datei, die Sie kontrollieren. Erstellen Sie sie einmal:

mkdir -p ~/.config/umami-mcp
cat > ~/.config/umami-mcp/env <<'EOF'
UMAMI_URL=https://analytics.example.com
UMAMI_USERNAME=mcp-bot
UMAMI_PASSWORD=your-password
UMAMI_MCP_MODE=read
EOF
chmod 600 ~/.config/umami-mcp/env

Der Server lädt sie automatisch. Er warnt beim Start, wenn die Datei für andere Benutzer lesbar ist.

Suchreihenfolge – die zuerst gefundene Datei gewinnt, und echte Umgebungsvariablen überschreiben immer die Datei, sodass Sie Einstellungen weiterhin von der Client-Konfiguration übergeben können, wenn Sie möchten:

1. $UMAMI_MCP_ENV_FILE, falls gesetzt

2. ~/.config/umami-mcp/env (oder $XDG_CONFIG_HOME/umami-mcp/env)

3. ./.env im Arbeitsverzeichnis

Verbinden Sie Ihren Client

Claude Code

Mit der obigen Anmeldedaten-Datei enthält die Registrierung überhaupt keine Geheimnisse:

claude mcp add umami --scope user -- node ~/umami-mcp/dist/index.js

Verwenden Sie den absoluten Pfad zu Ihrem Checkout. Wenn Ihr Node unter nvm lebt, geben Sie auch den vollständigen Interpreter-Pfad an, da MCP-Clients Ihr Shell-Profil nicht laden:

claude mcp add umami --scope user -- ~/.nvm/versions/node/v22.22.0/bin/node ~/umami-mcp/dist/index.js

Claude Desktop / Cursor / VS Code

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

Wenn Sie alles an einem Ort behalten möchten, funktionieren Umgebungsvariablen weiterhin und haben Vorrang vor der Datei:

{
  "mcpServers": {
    "umami": {
      "command": "node",
      "args": ["/absolute/path/to/umami-mcp/dist/index.js"],
      "env": {
        "UMAMI_URL": "https://analytics.example.com",
        "UMAMI_USERNAME": "mcp-bot",
        "UMAMI_PASSWORD": "your-password"
      }
    }
  }
}

Funktionsprüfung

Bitten Sie Ihren Client, umami_whoami auszuführen. Es meldet die Instanz, das Konto und den Berechtigungsmodus – der schnellste Weg, die Verbindung zu bestätigen und zu sehen, wie viel der Server darf:

{
  "instance": "https://analytics.example.com",
  "authenticatedAs": "mcp-bot",
  "role": "admin",
  "serverMode": "read",
  "destructiveOperations": "disabled"
}

Dann versuchen Sie: "Liste meine Umami-Websites auf", oder "Was waren meine Top-Seiten letzte Woche?"

Claude Web, Cowork und Claude Code im Web

Diese Clients können keinen lokalen Prozess starten, daher benötigen sie einen öffentlichen HTTPS-MCP-Server – und ihre Connector-Oberfläche akzeptiert nur OAuth, ohne Feld für ein statisches Bearer-Token oder einen benutzerdefinierten Header.

Das Offensichtliche zu hosten, mit einem Satz Umami-Anmeldedaten eingebacken und ohne Authentifizierung, macht die URL zu einem offenen Proxy für dieses Umami. Dieser Server macht also stattdessen OAuth – und das, ohne ein Anmeldedaten-Speicher zu werden.

Gehostete Instanz verwenden

Fügen Sie in Claude einen benutzerdefinierten Connector mit dieser URL hinzu:

https://umami-mcp.asif.dev/mcp

Claude registriert sich selbst, sendet Sie zu einem Zustimmungsbildschirm und fragt nach Ihrer eigenen Umami-URL, Benutzername und Passwort. Nichts wird mit anderen Benutzern des Hosts geteilt.

Eigenes Hosting

UMAMI_MCP_OAUTH=true
UMAMI_MCP_TRANSPORT=http
UMAMI_MCP_ISSUER=https://mcp.example.com      # public HTTPS URL of this server
UMAMI_MCP_TOKEN_KEY=<32 random bytes>          # keep stable; see below
UMAMI_MCP_TOKEN_TTL=2592000                    # 30 days

Generieren Sie den Schlüssel einmal und bewahren Sie ihn auf:

node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

Setzen Sie außerdem UMAMI_URL, um jeden Benutzer auf eine Instanz festzulegen, anstatt ihm die Wahl zu lassen.

Wie die Anmeldedaten behandelt werden

Der Zustimmungsbildschirm verifiziert die Anmeldedaten gegen die vom Benutzer benannte Umami-Instanz und versiegelt sie dann mit AES-256-GCM in das Zugriffstoken. Der Server führt keine Session-Tabelle und speichert keine Anmeldedaten: Jede Anfrage entschlüsselt das Token, erstellt einen MCP-Server, der auf diesen einen Benutzer beschränkt ist, bedient den Aufruf und verwirft ihn.

Der ehrliche Kompromiss: Wer UMAMI_MCP_TOKEN_KEY hält, kann jedes erfasste Token entschlüsseln. Behandeln Sie es als den sensibelsten Wert in der Bereitstellung. Eine Rotation macht jedes ausgestellte Token ungültig – das ist die beabsichtigte Blast-Radius-Kontrolle.

Zerstörerische Tools werden über OAuth niemals exponiert, egal welche Berechtigung der Benutzer wählt. Ihr getippter Bestätigungsschutz setzt einen lokalen Bediener voraus, der sehen kann, was er löschen wird, und einem entfernten Aufrufer kann das nicht gezeigt werden.

Als einfacher HTTP-Dienst ausführen

Setzen Sie UMAMI_MCP_TRANSPORT=http ohne UMAMI_MCP_OAUTH für einen Single-Tenant-Endpunkt unter /mcp, plus /health.

In diesem Modus hat der Server keine eigene Authentifizierung. Jeder, der den Port erreichen kann, kann Ihre Umami-Anmeldedaten verwenden. Halten Sie ihn auf Loopback und tunneln Sie zu ihm:

ssh -N -L 3334:127.0.0.1:3334 you@your-server
claude mcp add --transport http umami http://127.0.0.1:3334/mcp

Der Server warnt beim Start, wenn er an etwas anderes als Loopback gebunden ist.

Tools

Zeiträume

Jedes Analysetool akzeptiert eine period-Kurzform – 24h, 7d, 30d, 12m, today, yesterday – anstelle von Epochen-Millisekunden. Modelle sind zuverlässig gut bei „letzte 30 Tage“ und unzuverlässig gut bei Zeitstempel-Arithmetik, und ein falsch berechneter Epochenwert liefert Daten für das falsche Zeitfenster ohne Fehler. Explizite startAt/endAt in Epochen-Millisekunden funktionieren weiterhin und haben Vorrang.

Konfiguration

Siehe .env.example für alle Optionen. Die wichtigsten:

Empfohlene Einrichtung

Erstellen Sie ein dediziertes Umami-Konto für den MCP-Server, anstatt Ihren Admin-Login wiederzuverwenden, und geben Sie ihm nur die Websites, die er benötigt. Wenn die Anmeldedaten dann jemals offengelegt werden, ist der Schadensradius ein Bot-Konto, das Sie löschen können – nicht Ihr Administrator.

Kompatibilität

Verifiziert gegen Umami 3.3.1 (selbst gehostet, PostgreSQL). Umami Cloud funktioniert über UMAMI_API_KEY. Umami v2 wird nicht unterstützt: Die oben umbenannten Metriktypen bedeuten, dass v2 und v3 unterschiedliche Clients benötigen, und dieser zielt auf v3.

Entwicklung

npm install
npm run build
npm test          # unit tests, no network required

test/e2e.mjs und test/write-e2e.mjs steuern den gebauten Server über einen echten MCP-Client gegen eine Live-Instanz. Der Schreibtest erstellt eine Wegwerf-Website auf einer .invalid-Domain und löscht sie wieder; richten Sie ihn auf eine Nicht-Produktions-Instanz.

Mitwirken

Issues und Pull-Requests sind willkommen. Umami v3 stellt rund 127 API-Routen bereit, und dieser Server deckt die nützlichsten ab – Session Replay, Heatmaps, Pixel, Link-Tracking, Boards und Segmente sind noch nicht abgebildet. Wenn Sie Tools hinzufügen, halten Sie die Stufe und die destructive-Flags ehrlich, denn das gesamte Sicherheitsmodell beruht auf ihnen.

Wenn das Umami-Team dies übernehmen, forken oder upstreamen möchte, öffnen Sie bitte ein Issue – das ist das Ziel, für das dies gebaut wurde.

Lizenz

MIT © M Asif Rahman