PocketBase MCP Server

Interaja com uma instância do PocketBase para gerenciar registros e arquivos em coleções.

Documentação

PocketBase MCP Server

Este é um servidor MCP que interage com uma instância PocketBase. Ele permite buscar, listar, criar, atualizar e gerenciar registros e arquivos em suas coleções PocketBase.

Compatibilidade

Componente	Versão
Servidor PocketBase	>= v0.23 obrigatório (modelo de coleção `_superusers`); testado com v0.40.3 (estável mais recente no momento do lançamento)
SDK JS `pocketbase`	^0.28.1
`@modelcontextprotocol/sdk`	^1.30.0
Node.js	>= 18

Notas para servidores PocketBase mais recentes:

v0.27+: o tipo de campo geoPoint e a função de filtro geoDistance() são totalmente suportados por list_records / batch_records — veja Exemplos de filtro com geoPoint.
v0.40.x: Log.Data pode ser truncado pelo servidor (~16KB) e marcado com "__pb_truncated__": true; mensagens de log são limitadas a 8KB. A saída de list_logs / get_log repassa isso como está.
v0.38+: uma lista de permissões de IP para superusuário pode ser habilitada nas Configurações do PocketBase. Quando ativa, requisições de IPs fora da lista (incluindo o token deste MCP) são rejeitadas com HTTP 403 — veja Solução de Problemas.
v0.33+: ids de coleções/registros não podem conter . / \ | " ' ` < > : ? * % $ ou nomes reservados do Windows. Os geradores de migração validam isso antecipadamente.
v0.28+: o tipo de campo json tem um tamanho máximo padrão de 1MB; cargas maiores falham na validação em create_record / update_record.

Instalação

Instalando via Smithery

Para instalar o PocketBase MCP Server para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @mabeldata/pocketbase-mcp --client claude

Clone o repositório (se ainda não o fez):

git clone <repository_url>
cd pocketbase-mcp

Instale as dependências:
```
npm install
```
Compile o servidor:
```
npm run build
```
Isso compila o código TypeScript para JavaScript no diretório build/ e torna o ponto de entrada executável.

Testes

Suíte de testes (vitest, 3 camadas — guia completo em tests/TESTS.md):

npm test — testes unitários + de contrato (207: 195 passando + 12 marcadores documentados de bugs conhecidos; hermético: nenhuma instância PocketBase ou rede necessária). A camada de contrato trava o contrato MCP tools/list via snapshot (33 ferramentas: as 22 originais + 11 ferramentas aditivas do PR-3, cada grupo com snapshot separado), um handshake real Cliente↔Servidor via InMemoryTransport e um smoke test stdio do build/index.js compilado.
npm run test:integration — testes de integração contra um binário PocketBase real (56 testes): baixa/armazena em cache o binário automaticamente (POCKETBASE_VERSION para fixar, POCKETBASE_BIN para um binário local, PB_BIN_DIR para um cache alternativo), inicia uma instância efêmera em uma porta atribuída pelo SO com uma identidade de superusuário única e valida arquivos de migração gerados com o executor oficial migrate up/down. A suíte PR-3 (pr3-tools.test.ts) inicia sua própria instância dedicada (endpoints de escopo admin — SQL, batch, backups, configurações, limpeza de log — não devem competir com irmãos no servidor compartilhado; veja o cabeçalho do arquivo).
npm run test:all — a suíte completa (263 testes).
npm run typecheck — tsc sobre src + testes.
SKIP_KNOWN_BUG_TESTS=1 npm test — linha de base verde onde testes de marcadores de bugs conhecidos são pulados em vez de executados.

Scripts de smoke test de ponta a ponta (acionam o servidor compilado via stdio contra uma instância PocketBase real, 53 verificações):

npm run smoke:contract — smoke test apenas de contrato (tools/list via stdio, sem necessidade de PocketBase).
npm run smoke — smoke test completo: inicia um servidor efêmero a partir do binário em $POCKETBASE_BIN (padrão /tmp/pb-bin/pocketbase), cria um superusuário e então exercita todas as categorias de ferramentas (registros, coleções, arquivos, logs, crons, migrações) pelo canal JSON-RPC stdio.

CI (.github/workflows/ci.yml) executa build + typecheck + testes herméticos + testes de integração + smoke test em uma matriz de Node 18/20/22 × PocketBase v0.39.11/v0.40.3.

Configuração

Este servidor requer que as seguintes variáveis de ambiente sejam definidas:

POCKETBASE_API_URL: A URL da sua instância PocketBase (ex.: http://127.0.0.1:8090). O padrão é http://127.0.0.1:8090 se não for definida.
POCKETBASE_ADMIN_TOKEN: Um token de autenticação de admin para sua instância PocketBase. Isso é obrigatório. Você pode gerá-lo na interface de admin do PocketBase, veja API KEYS.
POCKETBASE_ENABLE_SQL: Opcional, desabilitado por padrão. Controla o acesso à ferramenta run_sql (execução de SQL bruto). Veja Execução de SQL (run_sql) abaixo — defina como true apenas se você entender os riscos.

Essas variáveis precisam ser configuradas ao adicionar o servidor ao Cline (veja a seção Instalação no Cline).

Ferramentas Disponíveis

O servidor fornece as seguintes ferramentas, organizadas por categoria:

Gerenciamento de Registros

fetch_record: Busca um único registro de uma coleção 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 uma coleção PocketBase. Suporta paginação, filtragem, ordenação e expansão de relações.

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: Cria um novo registro em uma coleção 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: Atualiza um registro existente em uma coleção 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: Exclui um registro de uma coleção 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: Executa múltiplas operações de registro (create/update/upsert/delete) em UM lote transacional — se qualquer operação falhar, todo o lote é revertido. Requer batch habilitado no servidor: no PocketBase >= v0.39, /api/batch está DESLIGADO por padrão; habilite via update_settings com {"batch": {"enabled": true}} (ou Admin UI -> Configurações), caso contrário as chamadas falham com 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: Obtém o esquema de uma coleção PocketBase.

Esquema de Entrada:

{
  "type": "object",
  "properties": {
    "collection": {
      "type": "string",
      "description": "The name of the PocketBase collection."
    }
  },
  "required": [
    "collection"
  ]
}

upload_file: Envia um arquivo para um campo específico em um registro de coleção 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 as coleções na instância PocketBase.
- Esquema de Entrada:
```
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

download_file: Obtém a URL de download para um arquivo armazenado em um registro de coleção 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 ferramenta retorna a URL do arquivo. O download real precisa ser realizado pelo cliente usando esta URL.

Exemplos de filtro: geoPoint

PocketBase >= v0.27 suporta o tipo de campo geoPoint e a função de filtro geoDistance(). Ambos funcionam de forma transparente através de list_records / create_record / update_record / batch_records (a string de filtro é passada ao servidor como está):

// 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" }

Os argumentos devem ser números simples ou identificadores de campo numéricos (location.lon / location.lat para um campo geoPoint); um literal de geometria como {-23.55, -46.63} NÃO é válido, e geoDistance() atualmente não é suportado em sort. Documentação oficial: https://pocketbase.io/docs/api-rules-and-filters/ (seção geoDistance).

Gerenciamento de Coleções

list_collections: Lista todas as coleções na instância PocketBase.
- Esquema de Entrada:
```
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

get_collection_schema: Obtém o esquema de uma coleção PocketBase.

Esquema de Entrada:

{
  "type": "object",
  "properties": {
    "collection": {
      "type": "string",
      "description": "The name of the PocketBase collection."
    }
  },
  "required": [
    "collection"
  ]
}

get_collection_scaffolds: Obtém exemplos de payloads de esquema de coleção (servidor >= v0.37) — um objeto chaveado por tipo de coleção (base, auth, view) com modelos prontos para edição para construir novas coleções.
- Esquema de Entrada: { "type": "object", "properties": {}, "additionalProperties": false }
dry_run_view_query: Valida uma consulta SQL de coleção VIEW sem salvar a coleção (servidor >= v0.37). Retorna as definições de campo resultantes e uma amostra de linhas, ou um erro de validação.
- Esquema de Entrada:
```
{
  "type": "object",
  "properties": {
    "query": { "type": "string", "description": "The SQL SELECT statement backing the view collection." }
  },
  "required": ["query"]
}
```

Gerenciamento de Logs

Nota: A API de Logs requer autenticação de admin e pode não estar disponível em todas as instâncias ou configurações PocketBase. Essas ferramentas interagem com a API de Logs do PocketBase conforme documentado em https://pocketbase.io/docs/api-logs/.

list_logs: Lista logs de requisições de API do PocketBase com filtragem, ordenação e paginação.

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: no PocketBase >= v0.40, o servidor pode truncar Log.Data (~16KB, marcado com "__pb_truncated__": true) e limitar mensagens de log a 8KB.

get_log: Obtém um único log de requisição 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: Obtém estatísticas de logs de requisições de API com filtragem opcional.

Esquema de Entrada:

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

truncate_logs: Exclui TODOS os logs de requisições de API (servidor >= v0.40). DESTRUTIVO e irreversível — requer confirm: true.

Esquema de Entrada:

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

Gerenciamento de Tarefas Agendadas (Cron)

Nota: A API de Tarefas Agendadas requer autenticação de admin e pode não estar disponível em todas as instâncias ou configurações PocketBase. Essas ferramentas interagem com a API de Tarefas Agendadas do PocketBase.

list_cron_jobs: Retorna uma lista com todas as tarefas agendadas registradas no nível do aplicativo.

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: Aciona uma única tarefa agendada pelo seu id.

Esquema de Entrada:

{
  "type": "object",
  "properties": {
    "jobId": {
      "type": "string",
      "description": "The identifier of the cron job to run."
    }
  },
  "required": [
    "jobId"
  ]
}

Gerenciamento de Backups

Nota: A API de Backup requer autenticação de superusuário (servidor >= v0.22). Documentação: https://pocketbase.io/docs/api-backups/.

list_backups: Lista todos os arquivos de backup disponíveis na instância (key, size, modified).
- Esquema de Entrada: { "type": "object", "properties": {}, "additionalProperties": false }
create_backup: Enfileira um novo backup de banco de dados + armazenamento. O name opcional deve terminar em .zip (apenas letras, dígitos, _, -); se omitido → o servidor gera pb_backup_<timestamp>.zip. Os backups são processados de forma assíncrona — consulte list_backups para a nova chave.
- Esquema de Entrada:
```
{
  "type": "object",
  "properties": {
    "name": { "type": "string", "description": "Optional backup filename ending in .zip." }
  },
  "required": []
}
```

restore_backup: Restaura a instância a partir de uma chave de backup existente. DESTRUTIVO: substitui TODOS os dados atuais. Requer 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"]
}

Gerenciamento de Configurações

Nota: A API de Configurações requer autenticação de superusuário. Segredos (senha SMTP, chaves S3, segredos de clientes OAuth2) são retornados pelo servidor mascarados como "******"; update_settings precisa dos NOVOS valores reais para esses campos (semântica PATCH — campos omitidos mantêm seus valores armazenados).

get_settings: Busca todas as configurações do aplicativo (seções: meta, logs, smtp, batch, backups, s3, rateLimits, ...).
- Esquema de Entrada: { "type": "object", "properties": {}, "additionalProperties": false }

update_settings: Atualiza configurações em massa com um payload parcial.

Esquema de Entrada:

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

Execução de SQL (run_sql — protegido por segurança)

run_sql executa SQL bruto arbitrário contra a instância PocketBase (servidor >= v0.39, endpoint POST /api/sql) com privilégios de superusuário. Como um servidor MCP é tipicamente acionado por um LLM — e LLMs podem ser manipulados por injeção de prompt nos dados que leem — esta ferramenta tem um raio de impacto muito maior do que as ferramentas de nível de registro e, portanto, é:

DESATIVADO POR PADRÃO. A ferramenta está sempre listada (contrato estável), mas toda chamada retorna um erro explicativo, a menos que o processo MCP tenha sido iniciado com POCKETBASE_ENABLE_SQL=true. Nenhuma solicitação de rede é feita quando o portão está fechado.
Tudo ou nada. Não há modo somente leitura: instruções SQL que modificam ou excluem dados (UPDATE, DELETE, DROP, PRAGMAs, ...) são tão executáveis quanto SELECT. Ative o portão apenas em instâncias em que você confia totalmente e, idealmente, em uma cópia dos seus dados (PocketBase é um arquivo único — faça backup primeiro com create_backup).
Auditável. Chamadas SQL entram nos logs de solicitação do PocketBase (POST /api/sql), então list_logs pode reconstruir o que foi executado.

Ative explicitamente, somente se você aceitar os riscos:

POCKETBASE_ENABLE_SQL=true node build/index.js

Uso típico (somente leitura) uma vez ativado:

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

Gerenciamento de Migrações

set_migrations_directory: Define o diretório onde os arquivos de migração serão criados e lidos.

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: Cria um novo arquivo de migração PocketBase vazio com um nome com carimbo de data/hora.

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: Cria um arquivo de migração especificamente para criar uma nova coleção 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: Cria um arquivo de migração para adicionar um campo a uma coleção 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 os arquivos de migração encontrados no diretório de migrações do PocketBase.
- Esquema de Entrada:
```
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

apply_migration: Aplica um arquivo de migração específico.

Esquema de Entrada:

{
  "type": "object",
  "properties": {
    "migrationFile": { 
      "type": "string", 
      "description": "Name of the migration file to apply." 
    }
  },
  "required": ["migrationFile"]
}

revert_migration: Reverte um arquivo de migração 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 as migrações pendentes.

Esquema de Entrada:

{
  "type": "object",
  "properties": {
    "appliedMigrations": { 
      "type": "array", 
      "items": { "type": "string" },
      "description": "Array of already applied migration filenames." 
    }
  }
}

revert_to_migration: Reverte migrações até um alvo 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 Migração

O PocketBase MCP Server inclui um sistema de migração para gerenciar mudanças no esquema do banco de dados. Este sistema permite que você:

Crie arquivos de migração com nomes com carimbo de data/hora
Gere migrações para operações comuns (criar coleções, adicionar campos)
Aplique e reverta migrações individualmente ou em lotes

Como aplicar/reverter funciona (e seus limites)

Arquivos de migração gerados por este MCP (create_collection_migration, add_field_migration) incorporam um comentário de marcador legível por máquina (// mcp-migration-meta: {...}) descrevendo suas operações como dados simples. apply_migration, revert_migration, apply_all_migrations e revert_to_migration executam essas operações através da API REST do PocketBase (pb.collections.*), que é o único canal disponível para um cliente MCP.

Arquivos de migração sem o marcador — por exemplo, migrações JSVM escritas manualmente no lado do servidor criadas com ./pocketbase migrate create — usam a API JSVM do servidor (migrate(), new Collection(), app.save()), que não existe em um cliente REST. Eles não podem ser aplicados através deste MCP; as ferramentas de aplicação retornam um erro explicativo apontando para ./pocketbase migrate up no host PocketBase. (Versões anteriores tentavam avaliar esses arquivos localmente com new Function, o que sempre falhava em tempo de execução.)

O rastreamento do estado aplicado não é armazenado no lado do servidor: apply_all_migrations / revert_to_migration recebem um parâmetro de array appliedMigrations (a tabela _migrations do servidor não é exposta a clientes REST). Mantenha essa lista em suas próprias ferramentas, ou aplique/reverta arquivos individuais.

Arquivos gerados permanecem migrações JSVM válidas, então o mesmo arquivo também pode ser aplicado no host com ./pocketbase migrate up (nesse caso, o PocketBase rastreia o estado em sua própria tabela _migrations — não misture ambos os caminhos de execução para o mesmo arquivo).

Formato do Arquivo de Migração

Arquivos de migração são arquivos JavaScript com um prefixo de carimbo de data/hora e um nome descritivo:

// 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 migração tem uma função "up" para aplicar mudanças e uma função "down" para revertê-las.

Exemplos de Uso

Definindo um diretório de migrações personalizado:

await setMigrationsDirectory("./my_migrations");

Criando uma migração básica:

await createNewMigration("add_user_email_index");

Criando uma migração de coleção:

await createCollectionMigration({
  id: "users",
  name: "users",
  fields: [
    { name: "email", type: "email", required: true }
  ]
});

Adicionando um campo a uma coleção:

await createAddFieldMigration("users", {
  name: "address",
  type: "text"
});

Aplicando migrações:

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

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

Revertendo migrações:

// 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);

Instalação no Cline

Para usar este servidor com o Cline, você precisa adicioná-lo ao seu arquivo de configurações MCP (cline_mcp_settings.json).

Localize seu arquivo de configurações MCP do Cline:
- Normalmente encontrado em ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json no Linux/macOS.
- Ou ~/Library/Application Support/Claude/claude_desktop_config.json se estiver usando o aplicativo de desktop Claude no macOS.

Edite o arquivo e adicione a seguinte configuração sob a chave mcpServers. Substitua /path/to/pocketbase-mcp pelo caminho absoluto real para este diretório de projeto no seu sistema. Além disso, substitua <YOUR_POCKETBASE_API_URL> e <YOUR_POCKETBASE_ADMIN_TOKEN> pela sua URL real do PocketBase e 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 ...
  }
}

Salve o arquivo de configurações. O Cline deve detectar automaticamente as mudanças e conectar ao servidor. Você pode então usar as ferramentas listadas acima.

Solução de Problemas

HTTP 403 em toda solicitação: desde o PocketBase v0.38, você pode habilitar uma lista de permissões de IP para superusuários (Admin UI -> Settings). Se habilitado, adicione o IP da máquina que executa este servidor MCP (ou desabilite a lista de permissões).
FATAL: POCKETBASE_ADMIN_TOKEN environment variable is required: a variável de ambiente do token não está definida; gere uma chave de API na interface de administração do PocketBase (superusuário -> API keys) e defina POCKETBASE_ADMIN_TOKEN.
Aviso de verificação de saúde no stderr na inicialização: o POCKETBASE_API_URL configurado está inacessível (instância fora do ar ou URL errada). O MCP ainda inicia para que tools/list funcione, mas as chamadas de ferramenta falharão até que a instância esteja acessível.
Cannot apply ...: This migration file does not contain MCP metadata: o arquivo é uma migração JSVM do lado do servidor; execute ./pocketbase migrate up no host PocketBase (veja Sistema de Migração).

Dependências

@modelcontextprotocol/sdk (^1.30.0)
pocketbase (^0.28.1)
typescript (dependência de desenvolvimento)
@types/node (dependência de desenvolvimento)