PocketBase MCP Server

Interactúa con una instancia de PocketBase para gestionar registros y archivos en colecciones.

Documentación

PocketBase MCP Server

Este es un servidor MCP que interactúa con una instancia de PocketBase. Permite obtener, listar, crear, actualizar y gestionar registros y archivos en tus colecciones de PocketBase.

Instalación

Instalación mediante Smithery

Para instalar PocketBase MCP Server para Claude Desktop automáticamente mediante 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
```
Instala las dependencias:
```
npm install
```
Compila el servidor:
```
npm run build
```
Esto compila el código TypeScript a JavaScript en el directorio build/ y hace ejecutable el punto de entrada.

Configuración

Este servidor requiere que se establezcan las siguientes variables de entorno:

POCKETBASE_API_URL: La URL de tu instancia de PocketBase (por ejemplo, http://127.0.0.1:8090). Por defecto, http://127.0.0.1:8090 si no se establece.
POCKETBASE_ADMIN_TOKEN: Un token de autenticación de administrador para tu instancia de PocketBase. Esto es obligatorio. Puedes generarlo desde la interfaz de administración de PocketBase, consulta API KEYS.

Estas variables deben configurarse al agregar el servidor a Cline (consulta la sección de Instalación de Cline).

Herramientas Disponibles

El servidor proporciona las siguientes herramientas, organizadas por categoría:

Gestión de Registros

fetch_record: Obtener un único registro de una colección de 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: Listar registros de una colección de PocketBase. Admite paginación, filtrado, ordenamiento 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: Crear 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: Actualizar 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: Obtener 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: Subir un archivo a 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: Listar todas las colecciones en la instancia de PocketBase.
- Esquema de entrada:
```
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

download_file: Obtener la URL de descarga para 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"
  ]
}

Nota: Esta herramienta devuelve la URL del archivo. La descarga real debe ser realizada por el cliente usando esta URL.

Gestión de Colecciones

list_collections: Listar todas las colecciones en la instancia de PocketBase.
- Esquema de entrada:
```
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

get_collection_schema: Obtener 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 (Logs)

Nota: La API de Logs requiere autenticación de administrador y puede no estar disponible en todas las instancias o configuraciones de PocketBase. Estas herramientas interactúan con la API de Logs de PocketBase como se documenta en https://pocketbase.io/docs/api-logs/.

list_logs: Listar los registros de solicitudes de API de PocketBase con filtrado, ordenamiento 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: Obtener 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: Obtener estadísticas de los 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 puede 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 registrados a nivel de aplicación.

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 Migraciones

set_migrations_directory: Establecer 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: Crear 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: Crear 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: Crear 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: Listar todos los archivos de migración encontrados 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: Revertir 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: Revertir 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 Migraciones

El PocketBase MCP Server incluye un sistema de migraciones completo para gestionar cambios en el esquema de la base de datos. Este sistema te 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 qué migraciones se han aplicado

Formato de Archivo de Migración

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 "up" para aplicar cambios y una función "down" para revertirlos.

Ejemplos de Uso

Establecer un directorio de migraciones personalizado:

await setMigrationsDirectory("./my_migrations");

Crear una migración básica:

await createNewMigration("add_user_email_index");

Crear 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"
});

Aplicar migraciones:

// Apply a specific migration
await applyMigration("1744005374_update_transactions_add_debt_link.js", pocketbaseInstance);

// Apply all pending migrations
await applyAllMigrations(pocketbaseInstance);

Revertir 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 usar este servidor con Cline, debes agregarlo a tu archivo de configuración de MCP (cline_mcp_settings.json).

Localiza tu archivo de configuración de MCP de Cline:
- Normalmente 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 usas la aplicación de escritorio de Claude en macOS.

Edita el archivo y agrega la siguiente configuración bajo la clave mcpServers. Reemplaza /path/to/pocketbase-mcp con la ruta absoluta real a este directorio del proyecto en tu sistema. También, reemplaza <YOUR_POCKETBASE_API_URL> y <YOUR_POCKETBASE_ADMIN_TOKEN> con tu URL real de PocketBase y token de administrador.

{
  "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 ...
  }
}

Guarda el archivo de configuración. Cline debería detectar automáticamente los cambios y conectarse al servidor. Luego puedes usar las herramientas listadas anteriormente.

Dependencias

@modelcontextprotocol/sdk
pocketbase
typescript
ts-node (dependencia de desarrollo)
@types/node (dependencia de desarrollo)