pocketbase-mcp-bridge

Servidor MCP para PocketBase

Documentación

Servidor MCP de PocketBase

Un servidor completo de Model Context Protocol para PocketBase. Expone toda la superficie de gestión de PocketBase — colecciones, registros, autenticación, archivos, logs, ajustes, copias de seguridad y cron jobs — como herramientas MCP que un asistente de IA (Claude Desktop, Claude Code, Cursor, etc.) puede llamar directamente.

Construido y validado contra PocketBase v0.39.6 usando el pocketbase SDK de JS oficial.

Características

55 herramientas en cada parte de la API de PocketBase:

Área	Herramientas
Salud y conexión	`health_check`, `auth_info`
Colecciones (esquema)	`list_collections`, `get_collection`, `get_collection_scaffolds`, `create_collection`, `update_collection`, `delete_collection`, `import_collections`, `truncate_collection`
Registros (datos)	`list_records`, `get_full_record_list`, `get_record`, `get_first_record`, `create_record`, `update_record`, `delete_record`, `batch`
Autenticación	`auth_with_password`, `list_auth_methods`, `impersonate`, `request_verification`, `confirm_verification`, `request_password_reset`, `confirm_password_reset`, `request_otp`, `auth_with_otp`, `confirm_email_change`, `list_external_auths`, `unlink_external_auth`
Superusuarios (administradores)	`list_superusers`, `create_superuser`, `update_superuser`, `delete_superuser`
Archivos	`get_file_url`, `get_file_token`, `download_file` (+ subidas vía `create_record`/`update_record`)
Logs	`list_logs`, `get_log`, `get_logs_stats`
Ajustes	`get_settings`, `update_settings`, `test_s3`, `test_email`, `generate_apple_client_secret`
Copias de seguridad	`list_backups`, `create_backup`, `upload_backup`, `delete_backup`, `restore_backup`, `get_backup_download_url`, `download_backup`
Cron jobs	`list_crons`, `run_cron`
Vía de escape	`send_raw_request` (llama a cualquier endpoint, incl. rutas de hooks personalizadas)

Aspectos destacados:

Auto-autenticación como superusuario desde variables de entorno, con re-autenticación transparente cuando el token expira.
Subidas/descargas de archivos desde/hacia el sistema de archivos local (multipart gestionado por ti).
Operaciones por lotes transaccionales (crear/actualizar/eliminar/upsert) en una sola petición.
Autenticación de usuario no destructiva — autenticarse como usuario final nunca sobrescribe la sesión de superusuario propia del MCP.
send_raw_request garantiza la completitud: cualquier cosa que las herramientas dedicadas no cubran (rutas personalizadas, nuevas características de la API) sigue siendo accesible.

Configuración

El servidor lee sus ajustes de conexión desde variables de entorno:

Variable	Requerida	Descripción
`POCKETBASE_URL`	✅	URL base, p. ej. `http://localhost:8090`. Prefiere `127.0.0.1` sobre `localhost` para evitar problemas de resolución IPv6.
`POCKETBASE_ADMIN_EMAIL`	✅*	Email del superusuario.
`POCKETBASE_ADMIN_PASSWORD`	✅*	Contraseña del superusuario.
`POCKETBASE_AUTH_COLLECTION`	–	Colección de autenticación para iniciar sesión (por defecto `_superusers`).
`POCKETBASE_TOKEN`	–	Usa un token pre-emitido en lugar de email/contraseña.

* Requerida a menos que se proporcione POCKETBASE_TOKEN.

Configuración del cliente MCP

Añade el servidor a tu cliente MCP (Claude Desktop claude_desktop_config.json, Claude Code, Cursor, …). La forma recomendada, sin instalación, usa npx:

{
  "mcpServers": {
    "pocketbase": {
      "command": "npx",
      "args": ["-y", "pocketbase-mcp-bridge"],
      "env": {
        "POCKETBASE_URL": "",
        "POCKETBASE_ADMIN_EMAIL": "",
        "POCKETBASE_ADMIN_PASSWORD": ""
      }
    }
  }
}

Rellena los tres valores de env con la URL de tu instancia y las credenciales de superusuario (mantén los secretos en env, nunca en args). La bandera -y permite a los clientes lanzar el servidor de forma no interactiva.

Alternativa: ejecutar desde una compilación local (sin npm install)

{
  "mcpServers": {
    "pocketbase": {
      "command": "node",
      "args": ["/absolute/path/to/pocketbase-mcp/dist/index.js"],
      "env": {
        "POCKETBASE_URL": "",
        "POCKETBASE_ADMIN_EMAIL": "",
        "POCKETBASE_ADMIN_PASSWORD": ""
      }
    }
  }
}

Alternativa: ejecutar vía Docker

{
  "mcpServers": {
    "pocketbase": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "POCKETBASE_URL",
        "-e", "POCKETBASE_ADMIN_EMAIL",
        "-e", "POCKETBASE_ADMIN_PASSWORD",
        "pocketbase-mcp-bridge"
      ],
      "env": {
        "POCKETBASE_URL": "http://host.docker.internal:8090",
        "POCKETBASE_ADMIN_EMAIL": "",
        "POCKETBASE_ADMIN_PASSWORD": ""
      }
    }
  }
}

Instalación

El paquete publicado funciona directamente con npx -y pocketbase-mcp-bridge (ver arriba) — no se necesita instalación manual una vez que esté en npm.

Para compilar desde el código fuente:

git clone https://github.com/nestebe/pocketbase-mcp.git
cd pocketbase-mcp
npm install
npm run build      # compiles TypeScript to dist/

El punto de entrada es dist/index.js (un servidor MCP stdio con un shebang #!/usr/bin/env node, también expuesto como binario pocketbase-mcp-bridge).

Imagen Docker

docker build -t pocketbase-mcp-bridge .
docker run -i --rm \
  -e POCKETBASE_URL=http://host.docker.internal:8090 \
  -e POCKETBASE_ADMIN_EMAIL=admin@example.com \
  -e POCKETBASE_ADMIN_PASSWORD=secret \
  pocketbase-mcp-bridge

La imagen es un servidor stdio — ejecútala con -i (interactivo) para que el cliente MCP pueda comunicarse con él a través de stdin/stdout.

Instancia de prueba local (`docker-test/`)

Se proporciona un PocketBase listo para ejecutar para desarrollo y validación:

docker compose -f docker-test/docker-compose.yml up -d

Panel de control: http://localhost:8090/_/
API REST: http://localhost:8090/api/
Superusuario (creado automáticamente en el primer arranque):
- email: admin@yourdomain.com
- contraseña: your-secure-password-here

Detener / restablecer:

docker compose -f docker-test/docker-compose.yml down          # stop
docker compose -f docker-test/docker-compose.yml down -v       # stop + wipe data

El cifrado de ajustes está intencionalmente deshabilitado en esta configuración local. Para producción, actívalo con una clave de 32 caracteres vía --encryptionEnv (ver los comentarios en docker-test/docker-compose.yml).

Ejecutar las pruebas de humo

Con el contenedor en ejecución:

node scripts/smoke-test.mjs             # collections, records, batch, settings, logs, crons...
node scripts/smoke-test-files-auth.mjs  # users auth, file upload/download, impersonation, backups

Ambas generan el servidor compilado a través de stdio y ejercitan las herramientas contra la instancia en vivo.

Notas de uso y trampas

PocketBase 0.23+ eliminó los campos implícitos created/updated. Las nuevas colecciones base no tienen columnas de marca de tiempo a menos que las añadas. Para ordenar por fecha de creación, añade campos autodate al crear la colección:
```
{ "name": "created", "type": "autodate", "onCreate": true },
{ "name": "updated", "type": "autodate", "onCreate": true, "onUpdate": true }
```
Consejo: llama a get_collection_scaffolds para obtener una plantilla que ya los incluya.
La API por lotes está deshabilitada por defecto. La herramienta batch devuelve "Batch requests are not allowed" hasta que la habilites: update_settings { "data": { "batch": { "enabled": true } } }.
Los administradores ahora son "superusuarios" — una colección de autenticación _superusers especial. Las herramientas *_superuser son envoltorios de conveniencia sobre operaciones de registros en ella.
Los flujos dependientes de email (verificación, restablecimiento de contraseña, OTP, email de prueba) requieren SMTP configurado en los ajustes.
Filtrado y ordenación usan la sintaxis de expresiones de PocketBase, p. ej. filter: 'status = "active" && created > "2024-01-01"', sort: '-created,title'. Usa expand para incluir relaciones en línea (p. ej. expand: 'author,comments_via_post').

Desarrollo

src/
  index.ts          # stdio entry point + eager auth
  server.ts         # builds the McpServer and registers every tool group
  config.ts         # env parsing
  pocketbase.ts     # SDK client singleton, auth, withAuth() retry helper
  util.ts           # tool result / error helpers
  formdata.ts       # multipart body builder for file uploads
  tools/
    health.ts collections.ts records.ts auth.ts superusers.ts
    files.ts logs.ts settings.ts backups.ts crons.ts raw.ts

npm run build     # tsc -> dist/
npm run watch     # tsc --watch
npm run dev       # run from TS via tsx (no build step)

Publicación (mantenedores)

El paquete se distribuye en npm y está listado en el Registro MCP oficial. Ambos están automatizados por .github/workflows/release.yml, activados cuando publicas un Release de GitHub.

Configuración única

Crea un token de acceso Automation (o granular, de lectura+escritura) de npm y añádelo como secreto del repositorio NPM_TOKEN. (Más tarde puedes migrar a Trusted Publishing / OIDC sin token y eliminar el secreto.)
El paso del Registro MCP usa GitHub OIDC (id-token: write) — no se necesita secreto. Publica bajo el espacio de nombres io.github.nestebe/*, verificado por el campo mcpName en package.json que coincide con el name en server.json.

Crear un release

npm version patch          # or minor / major — bumps package.json + creates a git tag
# keep server.json "version" in sync with package.json, then commit it
git push --follow-tags
gh release create v1.0.0 --generate-notes   # publishing the release fires the workflow

El flujo de trabajo entonces: compila → npm publish --provenance --access public → publica los metadatos server.json en el registro.

Publicación manual (sin CI)

npm publish --access public            # npm (must include the mcpName field)
# then, from the repo root:
mcp-publisher login github             # interactive GitHub OAuth (owner of "nestebe")
mcp-publisher publish                  # pushes server.json to registry.modelcontextprotocol.io

Antes de publicar, verifica el tarball y la salud del paquete:

npm publish --dry-run     # inspect exactly what ships
npx publint               # lint package.json/exports/bin for publish issues