Pocketbase

pocketbase-mcp

Servidor MCP remoto que conecta cualquier cliente MCP a una instancia de PocketBase a través de HTTP sin estado.

Inicio rápido

Usa la instancia alojada en https://pocketbase.tokenscompany.co/mcp o aloja la tuya propia.

Instalación con agente de IA

Copia y pega este prompt en tu agente de IA (Claude Code, Cursor, Windsurf, etc.):

Install the PocketBase MCP server. The MCP endpoint is https://pocketbase.tokenscompany.co/mcp and the transport type is http (NOT sse). It requires X-PB-URL set to my PocketBase instance URL and either X-PB-Email + X-PB-Password (superuser credentials) or X-PB-Token (superuser auth token). Add it to my project MCP config with type "http". Then fetch https://raw.githubusercontent.com/tokenscompany/pocketbase-mcp/main/SKILL.md and save it to my project's agent instructions so you always know how to use the PocketBase tools.

claude mcp add --transport http pocketbase https://pocketbase.tokenscompany.co/mcp \
  --header "X-PB-URL: https://your-pocketbase.example.com" \
  --header "X-PB-Email: admin@example.com" \
  --header "X-PB-Password: your-password"

{
  "mcpServers": {
    "pocketbase": {
      "type": "http",
      "url": "https://pocketbase.tokenscompany.co/mcp",
      "headers": {
        "X-PB-URL": "${PB_URL}",
        "X-PB-Email": "${PB_EMAIL}",
        "X-PB-Password": "${PB_PASSWORD}"
      }
    }
  }
}

{
  "mcpServers": {
    "pocketbase": {
      "url": "https://pocketbase.tokenscompany.co/mcp",
      "headers": {
        "X-PB-URL": "https://your-pocketbase.example.com",
        "X-PB-Email": "admin@example.com",
        "X-PB-Password": "your-password"
      }
    }
  }
}

{
  "mcp": {
    "pocketbase": {
      "type": "remote",
      "url": "https://pocketbase.tokenscompany.co/mcp",
      "headers": {
        "X-PB-URL": "https://your-pocketbase.example.com",
        "X-PB-Email": "admin@example.com",
        "X-PB-Password": "your-password"
      },
      "enabled": true
    }
  }
}

Autoalojamiento

Bun

bun install
bun run src/index.ts

El servidor escucha en PORT (por defecto 3000).

Docker (GHCR)

docker pull ghcr.io/tokenscompany/pocketbase-mcp:latest
docker run -p 3000:3000 ghcr.io/tokenscompany/pocketbase-mcp:latest

O compílalo localmente:

docker build -t pocketbase-mcp .
docker run -p 3000:3000 pocketbase-mcp

Verificación de la imagen

Cada imagen publicada en GHCR incluye atestación de procedencia SLSA. Puedes verificar que una imagen fue construida desde este repositorio:

gh attestation verify oci://ghcr.io/tokenscompany/pocketbase-mcp:latest \
  --owner tokenscompany

Autenticación

Cada solicitud a POST /mcp debe incluir X-PB-URL y uno de dos métodos de autenticación:

Opción 1: Correo electrónico + Contraseña (recomendado)

El servidor se autentica contra PocketBase en cada solicitud. No se necesita gestión manual de tokens.

Opción 2: Token

Para obtener un token manualmente:

curl -X POST https://your-pb.example.com/api/admins/auth-with-password \
  -H 'Content-Type: application/json' \
  -d '{"identity":"admin@example.com","password":"your-password"}'

El campo token en la respuesta es tu X-PB-Token. Si se proporcionan tanto el token como el correo electrónico y la contraseña, el token tiene prioridad.

Herramientas

Recursos

Seguridad y privacidad

Este servidor es completamente sin estado — no almacena, registra ni retiene ninguno de tus datos:

• Sin base de datos, sin escrituras en disco — cada solicitud crea un servidor MCP y transporte nuevos en memoria, los procesa y descarta todo. No se escribe nada en disco.
• Sin almacenamiento de credenciales — tus cabeceras X-PB-URL, X-PB-Token, X-PB-Email y X-PB-Password se usan durante la duración de la solicitud y nunca se persisten, almacenan en caché ni registran.
• Sin telemetría ni análisis — el servidor recopila cero datos de uso. No se contacta con servicios de terceros.
• Sin sesiones — no hay cookies, ni IDs de sesión, ni estado del lado del servidor entre solicitudes.
• Código abierto — todo el código base tiene licencia MIT. Cada imagen de Docker incluye atestación de procedencia SLSA, para que puedas verificar que fue construida directamente desde este repositorio sin modificaciones.
• Alójalo tú mismo — para máximo control, ejecuta tu propia instancia. El servidor es un solo contenedor sin dependencias externas más allá de tu instancia de PocketBase.

Endurecimiento

Al alojar una instancia pública, el servidor incluye varias medidas adicionales:

• Protección SSRF — X-PB-URL se valida: solo se permiten esquemas http/https, y se rechazan los nombres de host que resuelven a rangos de IP privados/reservados (127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16, ::1, fc00::/7, fe80::/10).

• Límite de velocidad — token-bucket en memoria por IP. Configurable mediante variables de entorno:

  Variable	Predeterminado	Descripción
  RATE_LIMIT_RPM	60	Solicitudes por minuto por IP
  RATE_LIMIT_BURST	10	Tamaño máximo de ráfaga

• CORS — Access-Control-Allow-Origin: * con soporte de preflight en /mcp.

• Límite de tamaño del cuerpo — las solicitudes mayores de 1 MB se rechazan con 413.

Endpoints

Solución de problemas

Error "Failed to reconnect"

La configuración de tu cliente MCP probablemente usa "type": "sse". Este servidor usa HTTP transmisible sin estado, no Server-Sent Events. Cambia el tipo de transporte a "http":

{
  "mcpServers": {
    "pocketbase": {
      "type": "http",
      ...
    }
  }
}

Para la CLI de Claude Code, usa --transport http al añadir:

claude mcp add --transport http pocketbase https://pocketbase.tokenscompany.co/mcp ...

Licencia

MIT