plausible-mcp

Un servidor MCP que permite que cualquier persona de una organización consulte Plausible Analytics desde Claude.

Un único despliegue sirve a toda la organización. Guarda una sola clave de API de Plausible en el servidor y autentica a cada persona con Google, de modo que nadie necesite su propia clave ni haya que conceder acceso a cada uno individualmente: pon tu dominio de Google Workspace en ALLOWED_DOMAINS y cualquiera con una dirección de ese dominio podrá conectarse la primera vez que lo intente. Las personas que trabajen fuera de ese dominio van en ALLOWED_EMAILS, una dirección cada vez.

Si te encargas de la analítica de un equipo y quieres que lean los números por sí mismos en lugar de pedírtelos, esto es exactamente para eso.

Cómo funciona la autenticación

Claude se registra en este servidor mediante el registro dinámico de clientes de OAuth 2.1. Google no es compatible con el registro dinámico de clientes, así que este servidor actúa como su propio servidor de autorización y delega el inicio de sesión de las personas en Google.

Google establece quién es la persona. No decide si puede leer tu analítica. Un middleware comprueba la dirección de correo verificada de cada llamador contra ALLOWED_DOMAINS y ALLOWED_EMAILS en cada llamada a una herramienta. Si no configuras ninguna de las dos, el servidor se niega a arrancar.

ALLOWED_DOMAINS es la parte que hace que esto valga para toda la organización: compara el dominio de la dirección verificada exactamente, así que example.com admite alice@example.com, pero no alice@evil-example.com ni alice@example.com.evil.com.

Para revocar a alguien, sácalo de ALLOWED_EMAILS o de ALLOWED_DOMAINS y vuelve a desplegar. Suspender su cuenta de Google impide que vuelva a iniciar sesión, pero la lista de permitidos lee las afirmaciones de un token que este servidor ha firmado, así que un token ya emitido sigue funcionando hasta que caduque. Cambiar JWT_SIGNING_KEY invalida todos los tokens a la vez, a costa de cerrar la sesión de todos.

Related MCP server: Plausible MCP

Herramientas

• query ejecuta una consulta de la API Stats API v2. Agrupar calibrando por dimensiones distintas te da series temporales, desglose de y conversiones de objetivo desde la misma herramienta. Para comparar dos periodos, llname una vez por cada viaje.

• list_sites devuelve los dominios de los sitios que puedes pasar como site_id.

• usage_stats informa de quién ha usado el servidor, con qué frecuencia y qué cuentas fueron rechazadas.

Seguimiento de uso

El middleware de la lista de permitidos ve la dirección de correo de cada llamador, porque tiene que comprobarla. Registra un recuento de llamadas por persona, la hora de la primera y de la última vez, y un desglose por herramienta en el volumen de USAGE_PATH. Las cuentas rechazadas se convierten por separado; así puedes localizar a personasde fuera de la lista que intenten conectarse.

Puedes leerlo con la herramienta usage_stats. Cualquiera que esté en la lista de permitidos puede ver las filas de todo el mundo. Deja sin definir USAGE_PATH para desactivar el seguimiento.

Configuración

Consulta .env.example para obtenerla la misma lista en formato listo para copiar y pegar.

Despliegue

El repositorio incluye un fly.toml, así que las instrucciones siguientes son para Fly.io, pero nada en el servidor es específico de Fly: es un único contenedor que necesita un directorio con permiso de escrit y el entorno de variables de más de una persona. Reemplaza YOUR-APP en todos los pasos.

1. Crea un cliente OAuth en la consola de Google Cloud. Elige Aplicación web and define la URI de redirección autorizada como https://YOUR-APP.fly.dev/auth/callback. Ese URI debe coincidir exactamente.

2. Crea la aplicación y su volumen de almacenamiento:

   fly apps create YOUR-APP --org YOUR-ORG
   fly volumes create plausible_mcp_data --app YOUR-APP --region fra --size 1 --yes

   Usa fly apps create en lugar de fly launch, que regeneraría el archivo fly.toml y descartaría el volumen y el checkeo de salud.

3. Apunta app en fly.toml al nombre de la aplicación.

4. Establece la configuración. BASE_URL y ALLOWED_DOMAINS deben ir aquí y no en fly.toml, porque deconfiguración por despliegue y un marcador de posición incluido en el repositorio sobrescuría en el ValueError del siguiente despliegue:

   fly secrets set --app YOUR-APP \
     BASE_URL=https://YOUR-APP.fly.dev \
     ALLOWED_DOMAINS=your-domain.org \
     GOOGLE_CLIENT_ID=xxx.apps.googleusercontent.com \
     GOOGLE_CLIENT_SECRET=GOCSPX-xxx \
     PLAUSIBLE_API_KEY=xxx \
     JWT_SIGNING_KEY="$(openssl rand -hex 32)"

   Mantén estable un JWT_SIGNING_KEY; cambiarlo cierra la sesión de todos.

5. fly deploy --ha=false

   Without --ha=false, Fly puede iniciar dos máquinas. Cada una tendría su propio volumen, por lo que una sesión que se registra en una máquina falla si la siguiente petición llega a la otra.

Añadirlo a Claude

Para añadirlo para todo un equipo, ve a Ajustes > Conectores en claude.ai, elige Añadirconector personalizado e introduce https://YOUR-APP.fly.dev/mcp. Cada persona iniciará sesión con Google la primera vez que lo use.

Para añadirlo a Claude Code:

claude mcp add --transport http plausible https://YOUR-APP.fly.dev/mcp

Ejecutarlo localmente

uv venv && uv pip install -r pyproject.toml
cp .env.example .env    # then fill it in
set -a && source .env && set +a
python server.py

Añade http://localhost:8000/auth/callback a los URIs de redirección del cliente de Google paraprobar el flujo de inicio de sesión local.

Ejecuta las pruebas con python test_server.py. Para probar manualmente el flujo de OAuth y las herramientas, usa npx @modelcontextprotocol/inspector.

Licencia

MIT — consulta LICENSE.