Servidor MCP de PocketBase
Este es un servidor MCP que interactúa con una instancia de PocketBase. Permite obtener, listar, crear, actualizar y administrar registros y archivos en sus colecciones de PocketBase.
Instalación
Para instalar PocketBase MCP Server para Claude Desktop automáticamente a través de Smithery :
npx -y @smithery/cli install @mabeldata/pocketbase-mcp --client claude
- Clona el repositorio (si aún no lo has hecho):
git clone <repository_url>
cd pocketbase-mcp
- Instalar dependencias:
- Construir el servidor:Esto compila el código TypeScript a JavaScript en el directorio
build/ y hace que el punto de entrada sea ejecutable.
Configuración
Este servidor requiere que se configuren las siguientes variables de entorno:
POCKETBASE_API_URL : La URL de su instancia de PocketBase (p. ej., http://127.0.0.1:8090 ). El valor predeterminado es http://127.0.0.1:8090 si no se configura.POCKETBASE_ADMIN_TOKEN : Un token de autenticación de administrador para su instancia de PocketBase. Es obligatorio. Puede generarlo desde la interfaz de administración de PocketBase; consulte las CLAVES DE API .
Estas variables deben configurarse al agregar el servidor a Cline (consulte la sección Instalación de Cline).
Herramientas disponibles
El servidor proporciona las siguientes herramientas, organizadas por categoría:
Gestión de registros
- fetch_record : obtiene un solo registro de una colección PocketBase por ID.
- Esquema de entrada :
{
"type": "object",
"properties": {
"collection": {
"type": "string",
"description": "The name of the PocketBase collection."
},
"id": {
"type": "string",
"description": "The ID of the record to fetch."
}
},
"required": [
"collection",
"id"
]
}
- list_records : Lista los registros de una colección de PocketBase. Admite paginación, filtrado, ordenación y expansión de relaciones.
- Esquema de entrada :
{
"type": "object",
"properties": {
"collection": {
"type": "string",
"description": "The name of the PocketBase collection."
},
"page": {
"type": "number",
"description": "Page number (defaults to 1).",
"minimum": 1
},
"perPage": {
"type": "number",
"description": "Items per page (defaults to 25).",
"minimum": 1,
"maximum": 100
},
"filter": {
"type": "string",
"description": "Filter string for the PocketBase query."
},
"sort": {
"type": "string",
"description": "Sort string for the PocketBase query (e.g., \\"fieldName,-otherFieldName\\")."
},
"expand": {
"type": "string",
"description": "Expand string for the PocketBase query (e.g., \\"relation1,relation2.subRelation\\")."
}
},
"required": [
"collection"
]
}
- create_record : crea un nuevo registro en una colección de PocketBase.
- Esquema de entrada :
{
"type": "object",
"properties": {
"collection": {
"type": "string",
"description": "The name of the PocketBase collection."
},
"data": {
"type": "object",
"description": "The data for the new record.",
"additionalProperties": true
}
},
"required": [
"collection",
"data"
]
}
- update_record : actualiza un registro existente en una colección de PocketBase.
- Esquema de entrada :
{
"type": "object",
"properties": {
"collection": {
"type": "string",
"description": "The name of the PocketBase collection."
},
"id": {
"type": "string",
"description": "The ID of the record to update."
},
"data": {
"type": "object",
"description": "The data to update.",
"additionalProperties": true
}
},
"required": [
"collection",
"id",
"data"
]
}
- get_collection_schema : obtiene el esquema de una colección de PocketBase.
- Esquema de entrada :
{
"type": "object",
"properties": {
"collection": {
"type": "string",
"description": "The name of the PocketBase collection."
}
},
"required": [
"collection"
]
}
- upload_file : carga un archivo en un campo específico en un registro de colección de PocketBase.
- Esquema de entrada :
{
"type": "object",
"properties": {
"collection": {
"type": "string",
"description": "The name of the PocketBase collection."
},
"recordId": {
"type": "string",
"description": "The ID of the record to upload the file to."
},
"fileField": {
"type": "string",
"description": "The name of the file field in the PocketBase collection."
},
"fileContent": {
"type": "string",
"description": "The content of the file to upload."
},
"fileName": {
"type": "string",
"description": "The name of the file."
}
},
"required": [
"collection",
"recordId",
"fileField",
"fileContent",
"fileName"
]
}
- list_collections : enumera todas las colecciones en la instancia de PocketBase.
- Esquema de entrada :
{
"type": "object",
"properties": {},
"additionalProperties": false
}
- download_file : obtiene la URL de descarga de un archivo almacenado en un registro de colección de PocketBase.
- Esquema de entrada :
{
"type": "object",
"properties": {
"collection": {
"type": "string",
"description": "The name of the PocketBase collection."
},
"recordId": {
"type": "string",
"description": "The ID of the record to download the file from."
},
"fileField": {
"type": "string",
"description": "The name of the file field in the PocketBase collection."
},
"downloadPath": {
"type": "string",
"description": "The path where the downloaded file should be saved (Note: This tool currently returns the URL, download must be handled separately)."
}
},
"required": [
"collection",
"recordId",
"fileField",
"downloadPath"
]
}
Gestión de cobros
- list_collections : enumera todas las colecciones en la instancia de PocketBase.
- Esquema de entrada :
{
"type": "object",
"properties": {},
"additionalProperties": false
}
- get_collection_schema : obtiene el esquema de una colección de PocketBase.
- Esquema de entrada :
{
"type": "object",
"properties": {
"collection": {
"type": "string",
"description": "The name of the PocketBase collection."
}
},
"required": [
"collection"
]
}
Gestión de registros
Nota: La API de registros requiere autenticación de administrador y podría no estar disponible en todas las instancias o configuraciones de PocketBase. Estas herramientas interactúan con la API de registros de PocketBase, como se documenta en https://pocketbase.io/docs/api-logs/ .
- list_logs : enumera los registros de solicitudes de API de PocketBase con filtrado, clasificación y paginación.
- Esquema de entrada :
{
"type": "object",
"properties": {
"page": {
"type": "number",
"description": "Page number (defaults to 1).",
"minimum": 1
},
"perPage": {
"type": "number",
"description": "Items per page (defaults to 30, max 500).",
"minimum": 1,
"maximum": 500
},
"filter": {
"type": "string",
"description": "PocketBase filter string (e.g., \"method='GET'\")."
}
},
"required": []
}
- get_log : obtiene un único registro de solicitud de API por ID.
- Esquema de entrada :
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The ID of the log to fetch."
}
},
"required": [
"id"
]
}
- get_logs_stats : obtiene estadísticas de registros de solicitudes de API con filtrado opcional.
- Esquema de entrada :
{
"type": "object",
"properties": {
"filter": {
"type": "string",
"description": "PocketBase filter string (e.g., \"method='GET'\")."
}
},
"required": []
}
Gestión de trabajos cron
Nota: La API de trabajos cron requiere autenticación de administrador y podría no estar disponible en todas las instancias o configuraciones de PocketBase. Estas herramientas interactúan con la API de trabajos cron de PocketBase.
- list_cron_jobs : Devuelve una lista con todos los trabajos cron de nivel de aplicación registrados.
- Esquema de entrada :
{
"type": "object",
"properties": {
"fields": {
"type": "string",
"description": "Comma separated string of the fields to return in the JSON response (by default returns all fields). Ex.:?fields=*,expand.relField.name"
}
}
}
- run_cron_job : activa un único trabajo cron por su id.
- Esquema de entrada :
{
"type": "object",
"properties": {
"jobId": {
"type": "string",
"description": "The identifier of the cron job to run."
}
},
"required": [
"jobId"
]
}
Gestión de la migración
- set_migrations_directory : establece el directorio donde se crearán y leerán los archivos de migración.
- Esquema de entrada :
{
"type": "object",
"properties": {
"customPath": {
"type": "string",
"description": "Custom path for migrations. If not provided, defaults to 'pb_migrations' in the current working directory."
}
}
}
- create_migration : crea un nuevo archivo de migración de PocketBase vacío con un nombre con marca de tiempo.
- Esquema de entrada :
{
"type": "object",
"properties": {
"description": {
"type": "string",
"description": "A brief description for the migration filename (e.g., 'add_user_email_index')."
}
},
"required": ["description"]
}
- create_collection_migration : crea un archivo de migración específicamente para crear una nueva colección de PocketBase.
- Esquema de entrada :
{
"type": "object",
"properties": {
"description": {
"type": "string",
"description": "Optional description override for the filename."
},
"collectionDefinition": {
"type": "object",
"description": "The full schema definition for the new collection (including name, id, fields, rules, etc.).",
"additionalProperties": true
}
},
"required": ["collectionDefinition"]
}
- add_field_migration : crea un archivo de migración para agregar un campo a una colección existente.
- Esquema de entrada :
{
"type": "object",
"properties": {
"collectionNameOrId": {
"type": "string",
"description": "The name or ID of the collection to update."
},
"fieldDefinition": {
"type": "object",
"description": "The schema definition for the new field.",
"additionalProperties": true
},
"description": {
"type": "string",
"description": "Optional description override for the filename."
}
},
"required": ["collectionNameOrId", "fieldDefinition"]
}
- list_migrations : enumera todos los archivos de migración que se encuentran en el directorio de migraciones de PocketBase.
- Esquema de entrada :
{
"type": "object",
"properties": {},
"additionalProperties": false
}
- apply_migration : aplicar un archivo de migración específico.
- Esquema de entrada :
{
"type": "object",
"properties": {
"migrationFile": {
"type": "string",
"description": "Name of the migration file to apply."
}
},
"required": ["migrationFile"]
}
- revert_migration : revierte un archivo de migración específico.
- Esquema de entrada :
{
"type": "object",
"properties": {
"migrationFile": {
"type": "string",
"description": "Name of the migration file to revert."
}
},
"required": ["migrationFile"]
}
- apply_all_migrations : Aplicar todas las migraciones pendientes.
- Esquema de entrada :
{
"type": "object",
"properties": {
"appliedMigrations": {
"type": "array",
"items": { "type": "string" },
"description": "Array of already applied migration filenames."
}
}
}
- revert_to_migration : revierte las migraciones hasta un objetivo específico.
- Esquema de entrada :
{
"type": "object",
"properties": {
"targetMigration": {
"type": "string",
"description": "Name of the migration to revert to (exclusive). Use empty string to revert all."
},
"appliedMigrations": {
"type": "array",
"items": { "type": "string" },
"description": "Array of already applied migration filenames."
}
},
"required": ["targetMigration"]
}
Sistema de Migración
El servidor PocketBase MCP incluye un sistema integral de migración para gestionar los cambios en el esquema de la base de datos. Este sistema le permite:
- Crear archivos de migración con nombres con marca de tiempo
- Generar migraciones para operaciones comunes (crear colecciones, agregar campos)
- Aplicar y revertir migraciones individualmente o en lotes
- Realizar un seguimiento de las migraciones que se han aplicado
Los archivos de migración son archivos JavaScript con un prefijo de marca de tiempo y un nombre descriptivo:
// 1744005374_update_transactions_add_debt_link.js
/// <reference path="../pb_data/types.d.ts" />
migrate((app) => {
// Up migration code here
return app.save();
}, (app) => {
// Down migration code here
return app.save();
});
Cada migración tiene una función "arriba" para aplicar cambios y una función "abajo" para revertirlos.
Ejemplos de uso
Configuración de un directorio de migraciones personalizado:
await setMigrationsDirectory("./my_migrations");
Creando una migración básica:
await createNewMigration("add_user_email_index");
Creación de una migración de colección:
await createCollectionMigration({
id: "users",
name: "users",
fields: [
{ name: "email", type: "email", required: true }
]
});
Agregar un campo a una colección:
await createAddFieldMigration("users", {
name: "address",
type: "text"
});
Aplicando migraciones:
// Apply a specific migration
await applyMigration("1744005374_update_transactions_add_debt_link.js", pocketbaseInstance);
// Apply all pending migrations
await applyAllMigrations(pocketbaseInstance);
Revirtiendo migraciones:
// Revert a specific migration
await revertMigration("1744005374_update_transactions_add_debt_link.js", pocketbaseInstance);
// Revert to a specific point (exclusive)
await revertToMigration("1743958155_update_transactions_add_relation_to_itself.js", pocketbaseInstance);
// Revert all migrations
await revertToMigration("", pocketbaseInstance);
Instalación de Cline
Para utilizar este servidor con Cline, debe agregarlo a su archivo de configuración de MCP ( cline_mcp_settings.json ).
- Localice el archivo de configuración de Cline MCP:
- Generalmente se encuentra en
~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json en Linux/macOS. - O
~/Library/Application Support/Claude/claude_desktop_config.json si usa la aplicación de escritorio Claude en macOS.
- Edite el archivo y agregue la siguiente configuración bajo la clave
mcpServers . Reemplace /path/to/pocketbase-mcp con la ruta absoluta a este directorio de proyecto en su sistema. Además, reemplace <YOUR_POCKETBASE_API_URL> y <YOUR_POCKETBASE_ADMIN_TOKEN> " con la URL y el token de administrador de PocketBase.{
"mcpServers": {
// ... other servers might be listed here ...
"pocketbase-mcp": {
"command": "node",
"args": ["/path/to/pocketbase-mcp/build/index.js"],
"env": {
"POCKETBASE_API_URL": "<YOUR_POCKETBASE_API_URL>", // e.g., "http://127.0.0.1:8090"
"POCKETBASE_ADMIN_TOKEN": "<YOUR_POCKETBASE_ADMIN_TOKEN>"
},
"disabled": false, // Ensure it's enabled
"autoApprove": [
"fetch_record",
"list_collections",
"get_collection_schema",
"list_logs",
"get_log",
"get_logs_stats",
"list_cron_jobs",
"run_cron_job"
] // Suggested auto-approve settings
}
// ... other servers might be listed here ...
}
}
- Guarde el archivo de configuración. Cline debería detectar los cambios automáticamente y conectarse al servidor. A continuación, puede usar las herramientas mencionadas anteriormente.
Dependencias
@modelcontextprotocol/sdkpocketbasetypescriptts-node (dependencia de desarrollo)@types/node (dependencia de desarrollo)