pocketbase-mcp

Un servidor del Protocolo de Contexto de Modelos (MCP) para PocketBase, que brinda a asistentes de IA como Claude acceso total a tu backend de PocketBase a través de una interfaz limpia y al estilo Python.

Descripción general

pocketbase-mcp cierra la brecha entre los LLM y tu instancia de PocketBase. Una vez conectado, los asistentes de IA pueden listar colecciones, realizar operaciones CRUD en registros, gestionar la autenticación, manejar subidas de archivos y administrar tu base de datos, todo mediante lenguaje natural.

Construido con FastMCP (el framework estándar de MCP para Python) y httpx para la comunicación HTTP asíncrona con la API REST de PocketBase.

Related MCP server: PocketBase MCP Server

Características

• Registros — listar, obtener, crear, actualizar, eliminar y realizar operaciones por lotes en registros de cualquier colección

• Colecciones — listar, inspeccionar, crear, actualizar y eliminar esquemas de colecciones

• Autenticación — autenticarse como superusuario o usuario normal mediante correo electrónico/contraseña o clave de API

• Archivos — generar tokens de archivo y recuperar URLs de archivos con transformaciones de imagen opcionales

• Configuración — leer y actualizar la configuración de la aplicación

• Filtrado y paginación — pasar expresiones de filtro, ordenamiento, expansión y parámetros de paginación de PocketBase directamente

• Consciente de tiempo real — diseñado teniendo en cuenta los patrones de suscripción SSE para futuras extensiones

Requisitos

• Python 3.11+

• Una instancia de PocketBase en ejecución (local o remota)

• uv (recomendado) o pip

Instalación

Usando pip

pip install pocketbase-mcp

Configuración

El servidor se configura mediante variables de entorno:

Establécelas en un archivo .env o expórtalas directamente:

export POCKETBASE_URL=http://127.0.0.1:8090
export POCKETBASE_SUPERUSER_EMAIL=admin@example.com
export POCKETBASE_SUPERUSER_PASSWORD=your-password

Ejecución del servidor

Transporte stdio (predeterminado — para Claude Desktop, Claude Code, etc.)

pocketmcp

Con MCP Inspector (para desarrollo y pruebas)

# Terminal 1
pocketmcp

# Terminal 2
npx @modelcontextprotocol/inspector
# Connect to: http://localhost:8000/mcp

Conexión a Claude

Claude Desktop

Añade lo siguiente a tu claude_desktop_config.json:

{
  "mcpServers": {
    "pocketbase": {
      "command": "uv",
      "args": ["run", "/absolute/path/to/pocketbase-mcp/server.py"],
      "env": {
        "POCKETBASE_URL": "http://127.0.0.1:8090",
        "POCKETBASE_SUPERUSER_EMAIL": "admin@example.com",
        "POCKETBASE_SUPERUSER_PASSWORD": "your-password"
      }
    }
  }
}

Herramientas disponibles

Registros

Colecciones

Autenticación

Archivos

Configuración

Estructura del proyecto

pocketbase-mcp/
├── server.py            # MCP server entry point (FastMCP)
├── tools/
│   ├── records.py       # Record CRUD tools
│   ├── collections.py   # Collection management tools
│   ├── auth.py          # Authentication tools
│   ├── files.py         # File tools
│   └── settings.py      # Settings tools
├── client.py            # Async PocketBase HTTP client (httpx)
├── config.py            # Environment variable loading
├── pyproject.toml
└── README.md

Ejemplo de uso

Una vez conectado a Claude, puedes interactuar con tu instancia de PocketBase mediante lenguaje natural:

"Lista todos los registros en la colección posts donde status = 'published', ordenados por created de forma descendente."

"Crea un nuevo registro en users con nombre 'Alice' y rol 'editor'."

"Muéstrame el esquema para la colección products."

"Elimina el registro con ID ae40239d2bc4477 de comments."

"Actualiza el nombre de la aplicación en la configuración de PocketBase a 'Mi App'."

Compatibilidad con PocketBase

Este servidor MCP apunta a PocketBase v0.36.9+. La API de lotes requiere que esté explícitamente habilitada en tu Panel de Control de PocketBase en Settings → Application.

Notas de seguridad

• Nunca subas credenciales al control de versiones. Usa variables de entorno o un archivo .env (añade .env a .gitignore).

• Para despliegues en producción, prefiere la autenticación mediante clave de API sobre el correo/contraseña.

• Las reglas de API de las colecciones en PocketBase gobiernan lo que el usuario autenticado puede acceder realmente; pocketbase-mcp respeta estas reglas.

Contribución

¡Las contribuciones son bienvenidas! Por favor, abre un issue antes de enviar una solicitud de extracción (pull request) para cambios significativos.

1. Haz un fork del repositorio

2. Crea una rama de funcionalidad (git checkout -b feat/mi-funcionalidad)

3. Confirma tus cambios

4. Abre una solicitud de extracción

Licencia

Licencia MIT. Consulta LICENSE para más detalles.