plausible-mcp

MCP-Server für Plausible Analytics – Traffic, Conversions abfragen und Zeiträume aus jedem KI-Tool vergleichen, das Model Context Protocol unterstützt.

Entwickelt für Teams, die Fragen stellen möchten wie:

• „Hat unser Deploy am Dienstag den Traffic auf /pricing beeinflusst?“

• „Wie hoch ist die Signup-Conversion-Rate auf /blog in diesem Monat?“

• „Wie vergleicht sich die Absprungrate dieser Woche mit der letzten Woche?“

Tools

Alle Abfragetools sind schreibgeschützt und mit readOnlyHint: true annotiert.

Gehostete Bereitstellungen bieten zusätzlich send_feedback, das Feedback über den Server selbst (verwirrende Fehler, fehlende Funktionen) in das Sentry User Feedback-Postfach der Maintainer einreicht. Es wird nur registriert, wenn der Server mit Sentry läuft (enableFeedbackTool).

Related MCP server: umami-mcp-server

Schnellstart

Remote (Gehostet)

Eine gehostete Instanz ist verfügbar unter https://plausible-mcp.sentry.dev.

Mit Ihrem eigenen Plausible-API-Schlüssel (beliebiger Benutzer):

claude mcp add --transport http plausible https://plausible-mcp.sentry.dev/mcp --header "Authorization: Bearer YOUR_PLAUSIBLE_API_KEY"

Behalten Sie die URL vor --header. --header ist variadisch. Wenn es also zuletzt kommt, verschluckt es die URL und die CLI schlägt fehl mit error: missing required argument 'commandOrUrl'.

Oder fügen Sie es manuell zu Ihrer MCP-Client-Konfiguration hinzu (Claude Desktop, Cursor usw.):

{
  "mcpServers": {
    "plausible": {
      "url": "https://plausible-mcp.sentry.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_PLAUSIBLE_API_KEY"
      }
    }
  }
}

Sentry-Mitarbeiter (über OAuth 2.1 + Cloudflare Access):

Der /internal-Endpunkt ist ein OAuth-2.1-Server – kein API-Schlüssel erforderlich. Fügen Sie ihn als Remote-/benutzerdefinierten Connector in jedem OAuth-fähigen MCP-Client hinzu (Cowork, Claude.ai-Connectors, Claude Desktop):

https://plausible-mcp.sentry.dev/internal

Der Client erkennt die OAuth-Endpunkte automatisch, führt Sie durch Sentry-SSO (Cloudflare Access), und nur @sentry.io-Identitäten erhalten Zugriff. Abfragen laufen gegen einen gemeinsamen, serverseitigen Plausible-API-Schlüssel – Sie haben nie einen Schlüssel in der Hand.

Das gehostete /internal unter plausible-mcp.sentry.dev ist nur für Sentry und kann außerhalb der Organisation nicht verwendet werden. Um /internal für eine andere Organisation auszuführen, self-hosten und ALLOWED_EMAIL_DOMAIN auf Ihre eigene Domain setzen. (Der öffentliche /mcp-Endpunkt mit eigenem Schlüssel hat keine solche Einschränkung.)

Lokal (STDIO)

Wenn Sie es lieber lokal ausführen möchten, verwenden Sie Node.js 20 oder neuer:

git clone https://github.com/getsentry/plausible-mcp.git
cd plausible-mcp
pnpm install
pnpm build

Zu Claude Code hinzufügen:

claude mcp add plausible -e PLAUSIBLE_API_KEY=your-key -- node /path/to/plausible-mcp/dist/index.js

Oder Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "plausible": {
      "command": "node",
      "args": ["/path/to/plausible-mcp/dist/index.js"],
      "env": {
        "PLAUSIBLE_API_KEY": "your-key"
      }
    }
  }
}

Self-Hosting (Cloudflare Workers)

Stellen Sie Ihre eigene Instanz bereit:

git clone https://github.com/getsentry/plausible-mcp.git
cd plausible-mcp
pnpm install
npx wrangler deploy

Der Worker stellt zwei Endpunkte bereit:

• /mcp – Bring-your-own-key. Jeder Benutzer übergibt seinen eigenen Plausible-API-Schlüssel über den Authorization: Bearer-Header. Keine gemeinsamen Geheimnisse auf dem Server erforderlich. Funktioniert mit jedem header-fähigen MCP-Client (Claude Code, Cursor, MCP Inspector).

• /internal – Zugriffsgeschützter MCP-Endpunkt für verwaltete Connectors (Cowork, Claude.ai). Eine Cloudflare-Access-Anwendung mit Managed OAuth liegt vor dem gesamten Worker-Hostnamen (siehe Einschränkung unten): Access führt den OAuth-2.1-Handshake mit dem Client durch und leitet jede Anfrage mit einem Cf-Access-Jwt-Assertion-Header an den Worker weiter. Der Worker verifiziert diesen Header und fragt einen gemeinsamen, serverseitigen Plausible-API-Schlüssel ab. Access ist auf die E-Mail-Domain(s) in ALLOWED_EMAIL_DOMAIN beschränkt (Standard: sentry.io) – nicht an Sentry gebunden, wenn Sie self-hosten; setzen Sie es auf Ihre eigene Domain.

Da die Managed-OAuth-Anwendung den nackten Hostnamen ohne Pfad abdecken muss (Cloudflare lehnt einen Pfad ab, wenn OAuth aktiviert ist – domain can not have a path if oauth is configured), schützt sie auch /mcp. Um den Bring-your-own-key-Endpunkt /mcp öffentlich zu halten, fügen Sie eine zweite, spezifischere Access-Anwendung hinzu, die auf den /mcp-Pfad mit einer Bypass-Richtlinie beschränkt ist. Cloudflare matcht zuerst den spezifischsten Hostnamen+Pfad, sodass /mcp-Anfragen Access vollständig umgehen, während alles andere durch OAuth läuft. Beide Apps leben auf einem Hostnamen; keine separate Subdomain erforderlich.

Beta / Client-Anforderung. Cloudflare Access Managed OAuth ist in der Beta und erfordert einen MCP-Client, der RFC 8707 unterstützt (Resource Indicators). Vergewissern Sie sich, dass Ihr Connector dies unterstützt, bevor Sie sich auf diesen Pfad verlassen.

Einrichten des /internal-Endpunkts (Cloudflare Access Managed OAuth)

Der Worker führt keinen OAuth-Server – Cloudflare Access ist der Autorisierungsserver. Es gibt kein OAUTH_KV, keinen Cookie-Schlüssel und keine OAuth-Client-ID/Secret. Sie erstellen zwei Access-Anwendungen auf demselben Hostnamen.

1. Erstellen Sie die Managed-OAuth-Anwendung über den nackten Hostnamen (Zero Trust → Access → Applications): eine Self-hosted-App oder MCP-Server-Anwendung, deren Domain plausible-mcp.sentry.dev ohne Pfad ist.

   • ⚠️ Nicht auf /internal beschränken. Sobald Managed OAuth aktiviert ist, lehnt Cloudflare jeden Pfad mit access.api.error.invalid_request: domain can not have a path if oauth is configured ab. Die App muss den gesamten Host abdecken; der Worker erzwingt die /internal-Route selbst.

   • Fügen Sie eine Access-Richtlinie (Aktion Allow) hinzu, die auf Ihre E-Mail-Domain (z. B. @acme.com) und Ihren Identitätsanbieter beschränkt.

   • Aktivieren Sie Managed OAuth (Erweiterte Einstellungen → Managed OAuth) und setzen Sie Erlaubte Redirect-URIs auf den tatsächlichen Callback Ihres Connectors – für Claude/Cowork ist das https://claude.ai/api/mcp/auth_callback. Öffentliche HTTPS-Callbacks müssen aufgeführt sein, sonst schlägt die Dynamic Client Registration mit invalid_client_metadata: redirect_uri is not allowed by the account configuration fehl; Loopback (http://localhost:*)-Callbacks sind standardmäßig erlaubt.

   • Kopieren Sie das AUD-Tag der Anwendung → dies wird CF_ACCESS_AUD.

2. Schneiden Sie /mcp mit einer zweiten, pfadbeschränkten Bypass-Anwendung wieder heraus. Da Schritt 1 den gesamten Host abdeckt, ist /mcp (Bring-your-own-key) jetzt ebenfalls geschützt. Erstellen Sie eine weitere Self-hosted-App, Domain plausible-mcp.sentry.dev Pfad mcp, mit Managed OAuth AUS, und einer Richtlinie, deren Aktion Bypass mit dem Selektor Everyone ist.

   • Bypass ≠ Allow: Eine Allow-Richtlinie erzwingt immer noch einen interaktiven Login (der Client erhält ein HTML-302 zur Login-Seite und schlägt fehl mit Unexpected content type: text/html). Nur Bypass lässt die Anfrage ohne Authentifizierung durch, sodass die eigene Bearer-Key-Prüfung des Workers greift.

3. Setzen Sie die Worker-Secrets:

   npx wrangler secret put PLAUSIBLE_API_KEY          # shared key for /internal queries
   npx wrangler secret put SENTRY_DSN                 # optional — the Worker's own telemetry

   CF_ACCESS_TEAM_DOMAIN und CF_ACCESS_AUD sind keine Secrets – eine öffentliche JWKS-URL und eine Anwendungskennung – also kommen sie in [vars] in Schritt 4.

4. Setzen Sie die [vars] in wrangler.toml:

   • CF_ACCESS_TEAM_DOMAIN – https://<team>.cloudflareaccess.com, ohne abschließenden Schrägstrich. Verifiziert die Cf-Access-Jwt-Assertion-JWKS und den Aussteller.

   • CF_ACCESS_AUD – das AUD-Tag, das Sie in Schritt 1 kopiert haben.

   • ALLOWED_EMAIL_DOMAIN – die E-Mail-Domain(s), die sich anmelden dürfen, durch Kommas getrennt, @ optional (Standard sentry.io). Wird im Code zusätzlich zur Access-Richtlinie in Schritt 1 erzwungen, also setzen Sie es auf Ihre eigene Domain – sonst wird jeder Login abgelehnt.

   • MCP_ALLOWED_HOSTNAMES – durch Kommas getrennte Hostnamen, die von den MCP-Endpunkten akzeptiert werden. Ersetzen Sie plausible-mcp.sentry.dev durch den Hostnamen Ihres Workers; behalten Sie die localhost-Einträge bei, wenn Sie wrangler dev verwenden.

   • MCP_ALLOWED_ORIGIN_HOSTNAMES – durch Kommas getrennte Browser-Origin-Hostnamen, die /internal aufrufen dürfen. Nicht-Browser-Clients senden keinen Origin-Header.

5. Bereitstellen (npx wrangler deploy), dann einen RFC-8707-fähigen MCP-Client auf https://<your-worker-host>/internal richten.

Fehlerbehebung. All dies sind Cloudflare-Access-Konfigurationen, nicht der Worker – eine Anfrage erreicht den Worker (und seine Sentry-Spans) erst, wenn Access sie weiterleitet:

Konfiguration

Auf dem Worker benötigt der /mcp-Endpunkt keinen serverseitigen Schlüssel — jeder Benutzer übergibt seinen eigenen über Authorization: Bearer. Der /internal-Endpunkt wird durch Cloudflare Access Managed OAuth abgesichert und verwendet ein gemeinsames serverseitiges PLAUSIBLE_API_KEY-Geheimnis (siehe Selbsthosting).

Plausible-API

Dieser Server kapselt die Plausible Stats API v2 (POST /api/v2/query). Er funktioniert sowohl mit Plausible Cloud als auch mit selbst gehosteten Instanzen.

Unterstützte Metriken

visitors, visits, pageviews, views_per_visit, bounce_rate, visit_duration, events, scroll_depth, percentage, conversion_rate, group_conversion_rate, average_revenue, total_revenue, time_on_page

Unterstützte Dimensionen

event:page, event:goal, event:hostname, visit:entry_page, visit:exit_page, visit:source, visit:referrer, visit:channel, visit:utm_medium, visit:utm_source, visit:utm_campaign, visit:utm_content, visit:utm_term, visit:device, visit:browser, visit:browser_version, visit:os, visit:os_version, visit:country, visit:region, visit:city, visit:country_name, visit:region_name, visit:city_name

Die Geographie-Dimensionen *_name geben menschenlesbare Namen zurück (z. B. „Kanada"); die einfachen visit:country/region/city geben ISO-/Geoname-Codes zurück.

Filtern

Jedes Query-Tool akzeptiert property_filters, die — trotz des Namens — sowohl nach eingebauten Dimensionen als auch nach benutzerdefinierten Event-Eigenschaften filtern. Jeder Eintrag ist { "property", "operator", "values" }:

• property — eine eingebaute Dimension (z. B. visit:channel, visit:source, event:page) oder eine benutzerdefinierte Eigenschaft mit ihrem bloßen Namen ("plan" zielt auf event:props:plan).

• operator — is, is_not, contains, contains_not (Standard is). event:goal unterstützt nur is und contains.

• Mehrere Einträge werden mit UND verknüpft, ebenso wie die Kurzparameter page/goal. Die gleichzeitige Verwendung von event:page/event:goal über einen Kurzparameter und property_filters im selben Aufruf wird abgelehnt — verwenden Sie entweder das eine oder das andere.

Beispiel: Top-Seiten für organischen Suchverkehr: get_breakdown mit dimension: "event:page" und property_filters: [{ "property": "visit:channel", "values": ["Organic Search"] }].

Benutzerdefinierte Eigenschaften

Sites senden ihre eigenen benutzerdefinierten Event-Eigenschaften, adressiert als event:props:<name>. Diese sind site-spezifisch, daher gibt es keine feste Liste.

• Aufschlüsselung nach einer benutzerdefinierten Eigenschaft: Übergeben Sie get_breakdown eine dimension von event:props:<name> (z. B. event:props:plan).

• Filtern nach einer benutzerdefinierten Eigenschaft über property_filters mit dem bloßen Namen, z. B. [{ "property": "plan", "operator": "is", "values": ["pro"] }].

Entwicklung

pnpm install
pnpm build         # TypeScript compilation
pnpm test          # Run unit + integration tests
pnpm test:watch    # Watch mode

Testen mit MCP Inspector

pnpm build
PLAUSIBLE_API_KEY=your-key npx @modelcontextprotocol/inspector node dist/index.js

LLM-Evals

Überprüft, ob das Modell das richtige Tool für natürlichsprachliche Analysefragen auswählt. Läuft über OpenRouter, sodass jedes Tool-Calling-Modell funktioniert — der Standard ist anthropic/claude-sonnet-5:

OPENROUTER_API_KEY=sk-or-... pnpm eval
OPENROUTER_MODEL=openai/gpt-5 OPENROUTER_API_KEY=sk-or-... pnpm eval  # try another model

Architektur

src/
├── index.ts              # STDIO entry point (local use)
├── worker.ts             # Cloudflare Worker entry point (remote)
├── env.ts                # Worker environment bindings
├── cf-access.ts          # Verifies the Cloudflare Access assertion on /internal
├── server.ts             # Creates McpServer, registers all tools
├── plausible.ts          # PlausibleClient — standalone API client
├── schemas.ts            # Shared Zod schemas and filter helpers
├── errors.ts             # UserFacingError and tool-error reporting
├── telemetry.ts          # Pure classifiers — route, MCP request kind, client family
├── mcp-telemetry.ts      # Records MCP client info onto the active span
├── redaction.ts          # Strips PII from Sentry events on the BYOK path
└── tools/
    ├── get-timeseries.ts
    ├── get-breakdown.ts
    ├── get-conversions.ts
    ├── compare-periods.ts
    └── send-feedback.ts

PlausibleClient hat keine MCP-Abhängigkeit und kann eigenständig verwendet werden.

Beobachtbarkeit & Datenerfassung

Der Worker meldet an Sentry mit einer endpunktabhängigen Datenschutz-Haltung:

• /mcp (Bring-your-own-key) — vollständig anonym. Tool-Eingaben und -Ausgaben werden nicht erfasst (diese Daten gehören dem Aufrufer und seinem eigenen Schlüssel), es wird keine Identität angehängt, und die vom Ingest abgeleitete Client-IP wird entfernt (src/redaction.ts). Es verbleibt nur operative Telemetrie: Tool-Namen, Span-Zeiten und Fehler.

• /internal (SSO-geschützt) — attribuiert. Anfragen tragen die authentifizierte @sentry.io-E-Mail (Sentry.setUser), und Tool-Eingaben/-Ausgaben werden erfasst (recordToolIO) für Attribuierung und Missbrauchs-Nachverfolgung auf dem gemeinsamen serverseitigen Schlüssel.

Authorization- / Cookie- / Cf-Access-Jwt-Assertion-Header werden auf beiden Pfaden aus Spans entfernt. Als zusätzliche Absicherung aktivieren Sie Prevent Storing of IP Addresses in den Security & Privacy-Einstellungen des Sentry-Projekts.

Lizenz

MIT — siehe LICENSE.