plausible-mcp

Servidor MCP para Plausible Analytics: consulta tráfico, conversiones y compara períodos de tiempo desde cualquier herramienta de IA compatible con Model Context Protocol.

Diseñado para equipos que quieren hacer preguntas como:

• "¿Nuestro despliegue del martes afectó al tráfico de /pricing?"

• "¿Cuál es la tasa de conversión de registro en /blog este mes?"

• "¿Cómo se compara la tasa de rebote de esta semana con la de la semana pasada?"

Herramientas

Todas las herramientas de consulta son de solo lectura y están anotadas con readOnlyHint: true.

Los despliegues alojados exponen además send_feedback, que envía comentarios sobre el propio servidor (errores confusos, capacidades faltantes) a la bandeja de entrada de User Feedback de Sentry de los mantenedores. Solo se registra cuando el servidor se ejecuta con Sentry (enableFeedbackTool).

Related MCP server: umami-mcp-server

Inicio rápido

Remoto (alojado)

Hay una instancia alojada disponible en https://plausible-mcp.sentry.dev.

Con tu propia clave de API de Plausible (cualquier usuario):

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

Mantén la URL antes de --header. --header es variádico, así que si va al final, se traga la URL y la CLI falla con error: missing required argument 'commandOrUrl'.

O añádelo manualmente a la configuración de tu cliente MCP (Claude Desktop, Cursor, etc.):

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

Empleados de Sentry (a través de OAuth 2.1 + Cloudflare Access):

El endpoint /internal es un servidor OAuth 2.1: no se necesita clave de API. Añádelo como conector remoto/personalizado en cualquier cliente MCP compatible con OAuth (Cowork, conectores de Claude.ai, Claude Desktop):

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

El cliente descubre automáticamente los endpoints OAuth, te envía a través del SSO de Sentry (Cloudflare Access) y solo se concede acceso a identidades @sentry.io. Las consultas se ejecutan contra una clave de API de Plausible compartida del lado del servidor: nunca manejas una clave.

El /internal alojado en plausible-mcp.sentry.dev es solo para Sentry y no se puede usar fuera de la organización. Para ejecutar /internal para otra organización, auto-aloja y establece ALLOWED_EMAIL_DOMAIN a tu propio dominio. (El endpoint público /mcp de trae-tu-propia-clave no tiene esa restricción).

Local (STDIO)

Si prefieres ejecutarlo localmente, usa Node.js 20 o superior:

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

Añádelo a Claude Code:

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

O a Claude Desktop (claude_desktop_config.json):

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

Auto-alojamiento (Cloudflare Workers)

Despliega tu propia instancia:

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

El worker expone dos endpoints:

• /mcp — trae-tu-propia-clave. Cada usuario pasa su propia clave de API de Plausible mediante la cabecera Authorization: Bearer. No se necesitan secretos compartidos en el servidor. Funciona con cualquier cliente MCP compatible con cabeceras (Claude Code, Cursor, MCP Inspector).

• /internal — endpoint MCP protegido por Access para conectores gestionados (Cowork, Claude.ai). Una aplicación de Cloudflare Access con OAuth gestionado protege todo el hostname del Worker (ver la restricción más abajo): Access realiza el protocolo OAuth 2.1 con el cliente y reenvía cada solicitud al Worker con una cabecera Cf-Access-Jwt-Assertion. El Worker verifica esa cabecera y consulta una clave de API de Plausible compartida del lado del servidor. Access está limitado a los dominios de correo en ALLOWED_EMAIL_DOMAIN (por defecto sentry.io) — no está vinculado a Sentry cuando te auto-alojas; establece tu propio dominio.

Debido a que la aplicación de OAuth gestionado debe cubrir el hostname desnudo sin ruta (Cloudflare rechaza una ruta cuando OAuth está habilitado — domain can not have a path if oauth is configured), también protege /mcp. Para mantener público el endpoint /mcp de trae-tu-propia-clave, añades una segunda aplicación Access más específica con ámbito en la ruta /mcp y una política Bypass. Cloudflare empareja primero el hostname+ruta más específico, así que las solicitudes a /mcp omiten Access por completo mientras que todo lo demás pasa por OAuth. Ambas aplicaciones viven en un solo hostname; no se requiere un subdominio separado.

Beta / requisito del cliente. El OAuth gestionado de Cloudflare Access está en Beta y requiere un cliente MCP que soporte RFC 8707 (indicadores de recurso). Confirma que tu conector lo soporta antes de depender de esta vía.

Configuración del endpoint /internal (OAuth gestionado de Cloudflare Access)

El Worker no ejecuta ningún servidor OAuth — Cloudflare Access es el servidor de autorización. No hay OAUTH_KV, ni clave de cookie, ni id/secreto de cliente OAuth. Creas dos aplicaciones Access en el mismo hostname.

1. Crea la aplicación de OAuth gestionado sobre el hostname desnudo (Zero Trust → Access → Applications): una aplicación auto-alojada o servidor MCP cuyo dominio sea plausible-mcp.sentry.dev sin ruta.

   • ⚠️ No la limites a /internal. Una vez que OAuth gestionado está habilitado, Cloudflare rechaza cualquier ruta con access.api.error.invalid_request: domain can not have a path if oauth is configured. La aplicación debe ser todo el host; el Worker aplica la ruta /internal por sí mismo.

   • Añade una política de Access (Acción Allow) que restrinja a tu dominio de correo (p. ej. @acme.com) y proveedor de identidad.

   • Habilita OAuth gestionado (Configuración avanzada → Managed OAuth) y establece Allowed redirect URIs al callback real de tu conector — para Claude/Cowork es https://claude.ai/api/mcp/auth_callback. Los callbacks HTTPS públicos deben estar listados o el registro dinámico de clientes falla con invalid_client_metadata: redirect_uri is not allowed by the account configuration; los callbacks de loopback (http://localhost:*) están permitidos por defecto.

   • Copia la etiqueta AUD de la aplicación → esto se convierte en CF_ACCESS_AUD.

2. Vuelve a separar /mcp con una segunda aplicación Bypass con ámbito de ruta. Como el paso 1 cubre todo el host, /mcp (trae-tu-propia-clave) ahora también está protegido. Crea otra aplicación auto-alojada, dominio plausible-mcp.sentry.dev ruta mcp, con OAuth gestionado DESACTIVADO, y una política cuya Acción sea Bypass con el selector Everyone.

   • Bypass ≠ Allow: una política Allow aún fuerza un inicio de sesión interactivo (el cliente recibe un 302 HTML a la página de inicio de sesión y falla con Unexpected content type: text/html). Solo Bypass deja pasar la solicitud sin autenticación, así que se aplica la verificación de clave Bearer del propio Worker.

3. Establece los secretos del worker:

   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 y CF_ACCESS_AUD no son secretos — una URL pública de JWKS y un identificador de aplicación — así que van en [vars] en el paso 4.

4. Establece los [vars] en wrangler.toml:

   • CF_ACCESS_TEAM_DOMAIN — https://<team>.cloudflareaccess.com, sin barra final. Verifica el JWKS y el emisor de Cf-Access-Jwt-Assertion.

   • CF_ACCESS_AUD — la etiqueta AUD que copiaste en el paso 1.

   • ALLOWED_EMAIL_DOMAIN — el(los) dominio(s) de correo permitidos para iniciar sesión, separados por comas, @ opcional (por defecto sentry.io). Se aplica en el código además de la política de Access del paso 1, así que establécelo a tu propio dominio — de lo contrario, cada inicio de sesión es rechazado.

   • MCP_ALLOWED_HOSTNAMES — hostnames separados por comas aceptados por los endpoints MCP. Reemplaza plausible-mcp.sentry.dev con el hostname de tu worker; mantén las entradas de localhost si usas wrangler dev.

   • MCP_ALLOWED_ORIGIN_HOSTNAMES — hostnames de Origin del navegador separados por comas permitidos para llamar a /internal. Los clientes que no son navegador no envían una cabecera Origin.

5. Despliega (npx wrangler deploy), y luego apunta un cliente MCP compatible con RFC 8707 a https://<tu-worker-host>/internal.

Solución de problemas. Todos estos son problemas de configuración de Cloudflare Access, no del Worker — una solicitud solo llega al Worker (y a sus spans de Sentry) una vez que Access la reenvía:

Configuración

En el Worker, el endpoint /mcp no necesita clave del lado del servidor — cada usuario pasa la suya propia vía Authorization: Bearer. El endpoint /internal está protegido por Cloudflare Access Managed OAuth y usa un secreto compartido PLAUSIBLE_API_KEY del lado del servidor (consulta autoalojamiento).

API de Plausible

Este servidor envuelve la Plausible Stats API v2 (POST /api/v2/query). Funciona tanto con Plausible Cloud como con instancias autoalojadas.

Métricas admitidas

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

Dimensiones admitidas

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

Las dimensiones geográficas *_name devuelven nombres legibles (p. ej. «Canadá»); las simples visit:country/region/city devuelven códigos ISO/Geoname.

Filtrado

Cada herramienta de consulta acepta property_filters, que — pese al nombre — filtra tanto por dimensiones integradas como por propiedades de evento personalizadas. Cada entrada es { "property", "operator", "values" }:

• property — una dimensión integrada (p. ej. visit:channel, visit:source, event:page) o una propiedad personalizada por su nombre simple ("plan" apunta a event:props:plan).

• operator — is, is_not, contains, contains_not (por defecto is). event:goal solo admite is y contains.

• Varias entradas se combinan con AND, al igual que los parámetros abreviados page/goal. Apuntar a event:page/event:goal a la vez desde un atajo y desde property_filters en la misma llamada se rechaza — usa uno u otro.

Por ejemplo, las páginas principales para tráfico de búsqueda orgánica: get_breakdown con dimension: "event:page" y property_filters: [{ "property": "visit:channel", "values": ["Organic Search"] }].

Propiedades personalizadas

Los sitios envían sus propias propiedades de evento personalizadas, referenciadas como event:props:<name>. Son específicas de cada sitio, por lo que no hay una lista fija.

• Desglosar por una propiedad personalizada: pasa a get_breakdown una dimension de event:props:<name> (p. ej. event:props:plan).

• Filtrar por una propiedad personalizada mediante property_filters con el nombre simple, p. ej. [{ "property": "plan", "operator": "is", "values": ["pro"] }].

Desarrollo

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

Pruebas con MCP Inspector

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

Evaluaciones LLM

Verifica que el modelo elige la herramienta correcta para preguntas analíticas en lenguaje natural. Se ejecuta a través de OpenRouter, por lo que cualquier modelo con llamada a herramientas funciona — el predeterminado es 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

Arquitectura

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 no tiene ninguna dependencia de MCP y puede usarse de forma independiente.

Observabilidad y recopilación de datos

El Worker informa a Sentry con una postura de privacidad que depende del endpoint:

• /mcp (trae tu propia clave) — totalmente anónimo. Las entradas y salidas de las herramientas no se registran (esos datos pertenecen a quien llama y a su propia clave), no se adjunta ninguna identidad, y la IP del cliente inferida por el ingesta se elimina (src/redaction.ts). Solo queda la telemetría operativa: nombres de herramientas, tiempos de span y fallos.

• /internal (protegido por SSO) — atribuido. Las solicitudes llevan el correo autenticado de @sentry.io (Sentry.setUser), y las entradas/salidas de las herramientas sí se registran (recordToolIO) para atribución y trazabilidad de abusos con la clave compartida del lado del servidor.

Las cabeceras Authorization / Cookie / Cf-Access-Jwt-Assertion se eliminan de los spans en ambas rutas. Como red de seguridad adicional, activa Prevent Storing of IP Addresses en los ajustes de Security & Privacy del proyecto de Sentry.

Licencia

MIT — consulta LICENSE.