PocketBase MCP Server

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

Documentación

Servidor MCP de PocketBase

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

Compatibilidad

Componente	Versión
Servidor PocketBase	>= v0.23 requerido (modelo de colección `_superusers`); probado contra v0.40.3 (última estable en el momento del lanzamiento)
SDK JS de `pocketbase`	^0.28.1
`@modelcontextprotocol/sdk`	^1.30.0
Node.js	>= 18

Notas para servidores PocketBase más nuevos:

v0.27+: el tipo de campo geoPoint y la función de filtro geoDistance() son totalmente compatibles con list_records / batch_records — consulta Ejemplos de filtro con geoPoint.
v0.40.x: Log.Data puede ser truncado por el servidor (~16KB) y marcado con "__pb_truncated__": true; los mensajes de registro están limitados a 8KB. La salida de list_logs / get_log pasa esto tal cual.
v0.38+: se puede habilitar una lista blanca de IP de superusuario en la Configuración de PocketBase. Cuando está activa, las solicitudes desde IPs fuera de la lista blanca (incluido el token de este MCP) se rechazan con HTTP 403 — consulta Solución de problemas.
v0.33+: los ids de colecciones/registros no pueden contener . / \ | " ' ` < > : ? * % $ ni nombres reservados de Windows. Los generadores de migración validan esto de antemano.
v0.28+: el tipo de campo json tiene un tamaño máximo predeterminado de 1MB; las cargas más grandes fallan la validación en create_record / update_record.

Instalación

Instalación mediante Smithery

Para instalar el Servidor MCP de PocketBase 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.

Pruebas

Suite de pruebas (vitest, 3 capas — guía completa en tests/TESTS.md):

npm test — pruebas unitarias + de contrato (207: 195 aprobadas + 12 marcadores documentados de errores conocidos; hermético: no requiere instancia de PocketBase ni red). La capa de contrato fija el contrato MCP de tools/list mediante instantánea (33 herramientas: las 22 originales + 11 herramientas aditivas del PR-3, cada grupo con instantánea separada), un handshake real Cliente↔Servidor sobre InMemoryTransport, y una prueba de humo stdio del build/index.js compilado.
npm run test:integration — pruebas de integración contra un binario real de PocketBase (56 pruebas): descarga/almacena en caché automáticamente el binario (POCKETBASE_VERSION para fijar, POCKETBASE_BIN para un binario local, PB_BIN_DIR para una caché alternativa), inicia una instancia efímera en un puerto asignado por el SO con una identidad de superusuario única, y valida los archivos de migración generados con el ejecutor oficial migrate up/down. La suite del PR-3 (pr3-tools.test.ts) inicia su propia instancia dedicada (los endpoints de ámbito admin — SQL, batch, copias de seguridad, configuración, borrado de registros — no deben competir con los hermanos en el servidor compartido; consulta el encabezado del archivo).
npm run test:all — la suite completa (263 pruebas).
npm run typecheck — tsc sobre src + pruebas.
SKIP_KNOWN_BUG_TESTS=1 npm test — línea base verde donde las pruebas de marcadores de errores conocidos se omiten en lugar de ejecutarse.

Scripts de humo de extremo a extremo (impulsan el servidor compilado sobre stdio contra una instancia real de PocketBase, 53 verificaciones):

npm run smoke:contract — humo solo de contrato (tools/list sobre stdio, no se necesita PocketBase).
npm run smoke — humo completo: inicia un servidor efímero desde el binario en $POCKETBASE_BIN (predeterminado /tmp/pb-bin/pocketbase), crea un superusuario, y luego ejercita cada categoría de herramienta (registros, colecciones, archivos, registros de log, crons, migraciones) sobre el canal JSON-RPC stdio.

CI (.github/workflows/ci.yml) ejecuta compilación + verificación de tipos + pruebas herméticas + pruebas de integración + humo en una matriz de Node 18/20/22 × PocketBase v0.39.11/v0.40.3.

Configuración

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

POCKETBASE_API_URL: La URL de tu instancia de PocketBase (p. ej., http://127.0.0.1:8090). Se establece por defecto a http://127.0.0.1:8090 si no se define.
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 CLAVES API.
POCKETBASE_ENABLE_SQL: Opcional, deshabilitado por defecto. Controla la herramienta run_sql (ejecución de SQL crudo). Consulta Ejecución SQL (run_sql) a continuación — solo establécelo a true si entiendes los riesgos.

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

Herramientas Disponibles

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

Gestión de Registros

fetch_record: Obtiene 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: Lista 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 30, max 500).",
      "minimum": 1,
      "maximum": 500
    },
    "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"
  ]
}

delete_record: Elimina un registro de una colección de PocketBase por ID (permanente).

Esquema de Entrada:

{
  "type": "object",
  "properties": {
    "collection": {
      "type": "string",
      "description": "The name or ID of the PocketBase collection."
    },
    "id": {
      "type": "string",
      "description": "The ID of the record to delete."
    }
  },
  "required": [
    "collection",
    "id"
  ]
}

batch_records: Ejecuta múltiples operaciones de registro (crear/actualizar/upsert/eliminar) en UN lote transaccional — si alguna operación falla, todo el lote se revierte. Requiere lote habilitado en el servidor: en PocketBase >= v0.39 /api/batch está DESACTIVADO por defecto; actívalo mediante update_settings con {"batch": {"enabled": true}} (o Interfaz de Admin -> Configuración), de lo contrario las llamadas fallan con HTTP 403 "Batch requests are not allowed".
- Esquema de Entrada:
```
{
  "type": "object",
  "properties": {
    "requests": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "collection": { "type": "string" },
          "action": { "enum": ["create", "update", "upsert", "delete"] },
          "id": { "type": "string" },
          "data": { "type": "object", "additionalProperties": true }
        },
        "required": ["collection", "action"]
      }
    }
  },
  "required": ["requests"]
}
```

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: Sube 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: Lista todas las colecciones en la instancia de PocketBase.
- Esquema de Entrada:
```
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

download_file: Obtiene 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 name of the record containing the file."
    },
    "fileField": {
      "type": "string",
      "description": "The name of the file field in the PocketBase collection."
    }
  },
  "required": [
    "collection",
    "recordId",
    "fileField"
  ]
}

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

Ejemplos de filtro: geoPoint

PocketBase >= v0.27 admite el tipo de campo geoPoint y la función de filtro geoDistance(). Ambos funcionan de manera transparente a través de list_records / create_record / update_record / batch_records (la cadena de filtro se pasa al servidor tal cual):

// store a location: create_record data payload (location is a geoPoint field)
{ "title": "Office", "location": { "lat": -23.5505, "lon": -46.6333 } }

// geoDistance(lonA, latA, lonB, latB) returns KILOMETRES (verified on v0.40.3) —
// offices within 10 km of São Paulo center (list_records filter):
{ "collection": "places", "filter": "geoDistance(location.lon, location.lat, -46.6333, -23.5505) <= 10" }

// combine with other conditions:
{ "collection": "places", "filter": "active = true && geoDistance(location.lon, location.lat, -46.6333, -23.5505) < 5" }

Los argumentos deben ser números simples o identificadores de campo numéricos (location.lon / location.lat para un campo geoPoint); un literal de geometría como {-23.55, -46.63} NO es válido, y geoDistance() actualmente no es compatible con sort. Documentación oficial: https://pocketbase.io/docs/api-rules-and-filters/ (sección geoDistance).

Gestión de Colecciones

list_collections: Lista 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"
  ]
}

get_collection_scaffolds: Obtiene ejemplos de cargas útiles de esquema de colección (servidor >= v0.37) — un objeto claveado por tipo de colección (base, auth, view) con plantillas listas para editar para construir nuevas colecciones.
- Esquema de Entrada: { "type": "object", "properties": {}, "additionalProperties": false }
dry_run_view_query: Valida una consulta SQL de colección VISTA sin guardar la colección (servidor >= v0.37). Devuelve las definiciones de campo resultantes y una muestra de filas, o un error de validación.
- Esquema de Entrada:
```
{
  "type": "object",
  "properties": {
    "query": { "type": "string", "description": "The SQL SELECT statement backing the view collection." }
  },
  "required": ["query"]
}
```

Gestión de Registros de Log

Nota: La API de Registros de Log 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 Registros de Log de PocketBase como se documenta en https://pocketbase.io/docs/api-logs/.

list_logs: Lista registros de solicitudes 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'\")."
    },
    "sort": {
      "type": "string",
      "description": "PocketBase sort string (e.g., \"-created,url\")."
    }
  },
  "required": []
}

Nota: en PocketBase >= v0.40 el servidor puede truncar Log.Data (~16KB, marcado con "__pb_truncated__": true) y limitar los mensajes de registro a 8KB.

get_log: Obtiene un único registro de solicitud 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 API con filtrado opcional.

Esquema de Entrada:

{
  "type": "object",
  "properties": {
    "filter": {
      "type": "string",
      "description": "PocketBase filter string (e.g., \"method='GET'\")."
    }
  },
  "required": []
}

truncate_logs: Elimina TODOS los registros de solicitudes API (servidor >= v0.40). DESTRUCTIVO e irreversible — requiere confirm: true.

Esquema de Entrada:

{
  "type": "object",
  "properties": {
    "confirm": { "type": "boolean", "description": "Must be explicitly true to delete all logs." }
  },
  "required": ["confirm"]
}

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 Copias de Seguridad

Nota: La API de Copias de Seguridad requiere autenticación de superusuario (servidor >= v0.22). Documentación: https://pocketbase.io/docs/api-backups/.

list_backups: Lista todos los archivos de copia de seguridad disponibles en la instancia (key, size, modified).
- Esquema de Entrada: { "type": "object", "properties": {}, "additionalProperties": false }
create_backup: Pone en cola una nueva copia de seguridad de base de datos+almacenamiento. El name opcional debe terminar en .zip (solo letras, dígitos, _, -); si se omite → el servidor genera pb_backup_<timestamp>.zip. Las copias de seguridad se procesan de forma asíncrona — consulta list_backups para la nueva clave.
- Esquema de Entrada:
```
{
  "type": "object",
  "properties": {
    "name": { "type": "string", "description": "Optional backup filename ending in .zip." }
  },
  "required": []
}
```

restore_backup: Restaura la instancia desde una clave de copia de seguridad existente. DESTRUCTIVO: reemplaza TODOS los datos actuales. Requiere confirm: true.

Esquema de Entrada:

{
  "type": "object",
  "properties": {
    "key": { "type": "string", "description": "Backup file key from list_backups." },
    "confirm": { "type": "boolean", "description": "Must be explicitly true." }
  },
  "required": ["key", "confirm"]
}

Gestión de Configuración

Nota: La API de Configuración requiere autenticación de superusuario. Los secretos (contraseña SMTP, claves S3, secretos de cliente OAuth2) son devueltos por el servidor enmascarados como "******"; update_settings necesita los valores REALES nuevos para esos campos (semántica PATCH — los campos omitidos conservan sus valores almacenados).

get_settings: Obtiene toda la configuración de la aplicación (secciones: meta, logs, smtp, batch, backups, s3, rateLimits, ...).
- Esquema de Entrada: { "type": "object", "properties": {}, "additionalProperties": false }

update_settings: Actualiza masivamente la configuración con una carga útil parcial.

Esquema de Entrada:

{
  "type": "object",
  "properties": {
    "data": { "type": "object", "description": "Partial settings payload, e.g. { \"logs\": { \"maxDays\": 14 } }.", "additionalProperties": true }
  },
  "required": ["data"]
}

Ejecución SQL (run_sql — controlado por seguridad)

run_sql ejecuta SQL crudo arbitrario contra la instancia de PocketBase (servidor >= v0.39, endpoint POST /api/sql) con privilegios de superusuario. Debido a que un servidor MCP típicamente es impulsado por un LLM — y los LLM pueden ser dirigidos por inyección de prompts en los datos que leen — esta herramienta tiene un radio de explosión mucho mayor que las herramientas a nivel de registro y por lo tanto está:

DESHABILITADO POR DEFECTO. La herramienta siempre aparece listada (contrato estable), pero cada llamada devuelve un error explicativo a menos que el proceso MCP se haya iniciado con POCKETBASE_ENABLE_SQL=true. No se realiza ninguna solicitud de red cuando la puerta está cerrada.
Todo o nada. No existe un modo de solo lectura: las sentencias SQL que modifican o eliminan datos (UPDATE, DELETE, DROP, PRAGMAs, ...) son tan ejecutables como SELECT. Solo habilita la puerta en instancias en las que confíes plenamente y, idealmente, en una copia de tus datos (PocketBase es un solo archivo: haz una copia de seguridad primero con create_backup).
Auditable. Las llamadas SQL aparecen en los registros de solicitudes de PocketBase (POST /api/sql), por lo que list_logs puede reconstruir lo que se ejecutó.

Habilítalo explícitamente, solo si aceptas los riesgos:

POCKETBASE_ENABLE_SQL=true node build/index.js

Uso típico (solo lectura) una vez habilitado:

{ "name": "run_sql", "arguments": { "query": "SELECT COUNT(*) AS n FROM posts" } }

Gestión de Migraciones

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: Lista todos los archivos de migración encontrados en el directorio de migraciones de PocketBase.
- Esquema de entrada:
```
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

apply_migration: Aplica 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: Aplica 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 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 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

Cómo funciona aplicar/revertir (y sus límites)

Los archivos de migración generados por este MCP (create_collection_migration, add_field_migration) incorporan un comentario marcador legible por máquina (// mcp-migration-meta: {...}) que describe sus operaciones como datos simples. apply_migration, revert_migration, apply_all_migrations y revert_to_migration ejecutan esas operaciones a través de la API REST de PocketBase (pb.collections.*), que es el único canal disponible para un cliente MCP.

Los archivos de migración sin el marcador — por ejemplo, migraciones JSVM escritas a mano en el servidor creadas con ./pocketbase migrate create — usan la API JSVM del servidor (migrate(), new Collection(), app.save()), que no existe en un cliente REST. No se pueden aplicar a través de este MCP; las herramientas de aplicación devuelven un error explicativo que apunta a ./pocketbase migrate up en el host de PocketBase. (Las versiones anteriores intentaban evaluar esos archivos localmente con new Function, lo que siempre fallaba en tiempo de ejecución).

El seguimiento del estado aplicado no se almacena en el servidor: apply_all_migrations / revert_to_migration toman un parámetro de matriz appliedMigrations (la tabla _migrations del servidor no está expuesta a los clientes REST). Mantén esa lista en tus propias herramientas, o aplica/revierte archivos individuales.

Los archivos generados siguen siendo migraciones JSVM válidas, por lo que el mismo archivo también se puede aplicar en el host con ./pocketbase migrate up (en cuyo caso PocketBase rastrea el estado en su propia tabla _migrations — no mezcles ambas rutas de ejecución para el mismo archivo).

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" />
// mcp-migration-meta: {"ops":{"up":[...],"down":[...]}}   <- only in MCP-generated files
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

Configurar 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 en 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 tu 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.

Solución de Problemas

HTTP 403 en cada solicitud: desde PocketBase v0.38 puedes habilitar una lista blanca de IP para superusuarios (Interfaz de Administración -> Configuración). Si está habilitada, agrega la IP de la máquina que ejecuta este servidor MCP (o deshabilita la lista blanca).
FATAL: POCKETBASE_ADMIN_TOKEN environment variable is required: la variable de entorno del token no está configurada; genera una clave API en la interfaz de administración de PocketBase (superusuario -> claves API) y configura POCKETBASE_ADMIN_TOKEN.
Advertencia de verificación de salud en stderr al inicio: el POCKETBASE_API_URL configurado es inalcanzable (instancia caída o URL incorrecta). El MCP aún se inicia para que tools/list funcione, pero las llamadas a herramientas fallarán hasta que la instancia sea alcanzable.
Cannot apply ...: This migration file does not contain MCP metadata: el archivo es una migración JSVM del lado del servidor; ejecuta ./pocketbase migrate up en el host de PocketBase en su lugar (consulta el Sistema de Migraciones).

Dependencias

@modelcontextprotocol/sdk (^1.30.0)
pocketbase (^0.28.1)
typescript (dependencia de desarrollo)
@types/node (dependencia de desarrollo)