pocketbase-mcp-bridge

Servidor MCP PocketBase

Um servidor completo do Model Context Protocol para PocketBase. Ele expõe toda a superfície de gerenciamento do PocketBase — coleções, registros, autenticação, arquivos, logs, configurações, backups e crons — como ferramentas MCP que um assistente de IA (Claude Desktop, Claude Code, Cursor, etc.) pode chamar diretamente.

Construído e validado contra o PocketBase v0.39.6 usando o pocketbase JS SDK oficial.

Recursos

55 ferramentas em todas as partes da API do PocketBase:

Destaques:

• Autenticação automática como superusuário a partir de variáveis de ambiente, com reautenticação transparente quando o token expira.
• Uploads/downloads de arquivos de/para o sistema de arquivos local (multipart tratado para você).
• Operações em lote transacionais (create/update/delete/upsert) em uma única requisição.
• Autenticação de usuário não destrutiva — autenticar como usuário final nunca sobrescreve a sessão de superusuário do próprio MCP.
• send_raw_request garante completude: qualquer coisa que as ferramentas dedicadas não cobrem (rotas personalizadas, novos recursos da API) ainda é acessível.

Configuração

O servidor lê suas configurações de conexão das variáveis de ambiente:

* Obrigatória a menos que POCKETBASE_TOKEN seja fornecida.

Configuração do cliente MCP

Adicione o servidor ao seu cliente MCP (Claude Desktop claude_desktop_config.json, Claude Code, Cursor, …). A forma recomendada, sem instalação, usa npx:

{
  "mcpServers": {
    "pocketbase": {
      "command": "npx",
      "args": ["-y", "pocketbase-mcp-bridge"],
      "env": {
        "POCKETBASE_URL": "",
        "POCKETBASE_ADMIN_EMAIL": "",
        "POCKETBASE_ADMIN_PASSWORD": ""
      }
    }
  }
}

Preencha os três valores de env com a URL da sua instância e as credenciais de superusuário (mantenha segredos em env, nunca em args). A flag -y permite que os clientes iniciem o servidor de forma não interativa.

{
  "mcpServers": {
    "pocketbase": {
      "command": "node",
      "args": ["/absolute/path/to/pocketbase-mcp/dist/index.js"],
      "env": {
        "POCKETBASE_URL": "",
        "POCKETBASE_ADMIN_EMAIL": "",
        "POCKETBASE_ADMIN_PASSWORD": ""
      }
    }
  }
}

{
  "mcpServers": {
    "pocketbase": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "POCKETBASE_URL",
        "-e", "POCKETBASE_ADMIN_EMAIL",
        "-e", "POCKETBASE_ADMIN_PASSWORD",
        "pocketbase-mcp-bridge"
      ],
      "env": {
        "POCKETBASE_URL": "http://host.docker.internal:8090",
        "POCKETBASE_ADMIN_EMAIL": "",
        "POCKETBASE_ADMIN_PASSWORD": ""
      }
    }
  }
}

Instalação

O pacote publicado funciona prontamente com npx -y pocketbase-mcp-bridge (veja acima) — nenhuma instalação manual é necessária depois que estiver no npm.

Para compilar a partir do código-fonte:

git clone https://github.com/nestebe/pocketbase-mcp.git
cd pocketbase-mcp
npm install
npm run build      # compiles TypeScript to dist/

O ponto de entrada é dist/index.js (um servidor MCP stdio com um shebang #!/usr/bin/env node, também exposto como o binário pocketbase-mcp-bridge).

Imagem Docker

docker build -t pocketbase-mcp-bridge .
docker run -i --rm \
  -e POCKETBASE_URL=http://host.docker.internal:8090 \
  -e POCKETBASE_ADMIN_EMAIL=admin@example.com \
  -e POCKETBASE_ADMIN_PASSWORD=secret \
  pocketbase-mcp-bridge

A imagem é um servidor stdio — execute-a com -i (interativo) para que o cliente MCP possa se comunicar com ele via stdin/stdout.

Instância de teste local (docker-test/)

Um PocketBase pronto para execução é fornecido para desenvolvimento e validação:

docker compose -f docker-test/docker-compose.yml up -d

• Dashboard: http://localhost:8090/_/
• API REST: http://localhost:8090/api/
• Superusuário (criado automaticamente no primeiro boot):
  • e-mail: admin@yourdomain.com
  • senha: your-secure-password-here

Parar / redefinir:

docker compose -f docker-test/docker-compose.yml down          # stop
docker compose -f docker-test/docker-compose.yml down -v       # stop + wipe data

A criptografia de configurações está intencionalmente desativada nesta configuração local. Para produção, ative-a com uma chave de 32 caracteres via --encryptionEnv (veja os comentários em docker-test/docker-compose.yml).

Executar os testes de fumaça

Com o contêiner em execução:

node scripts/smoke-test.mjs             # collections, records, batch, settings, logs, crons...
node scripts/smoke-test-files-auth.mjs  # users auth, file upload/download, impersonation, backups

Ambos iniciam o servidor compilado via stdio e exercitam as ferramentas contra a instância ativa.

Notas de uso e pegadinhas

• O PocketBase 0.23+ removeu os campos implícitos created/updated. Novas coleções base não têm colunas de timestamp, a menos que você as adicione. Para ordenar por data de criação, adicione campos autodate ao criar a coleção:

  { "name": "created", "type": "autodate", "onCreate": true },
  { "name": "updated", "type": "autodate", "onCreate": true, "onUpdate": true }
  

  Dica: chame get_collection_scaffolds para obter um modelo que já os inclui.
• A API em lote está desativada por padrão. A ferramenta batch retorna "Batch requests are not allowed" até que você a ative: update_settings { "data": { "batch": { "enabled": true } } }.
• Administradores agora são "superusuários" — uma coleção de autenticação _superusers especial. As ferramentas *_superuser são wrappers de conveniência sobre operações de registro nela.
• Fluxos dependentes de e-mail (verificação, redefinição de senha, OTP, e-mail de teste) exigem SMTP configurado nas configurações.
• Filtragem e ordenação usam a sintaxe de expressão do PocketBase, ex.: filter: 'status = "active" && created > "2024-01-01"', sort: '-created,title'. Use expand para incorporar relações inline (ex.: expand: 'author,comments_via_post').

Desenvolvimento

src/
  index.ts          # stdio entry point + eager auth
  server.ts         # builds the McpServer and registers every tool group
  config.ts         # env parsing
  pocketbase.ts     # SDK client singleton, auth, withAuth() retry helper
  util.ts           # tool result / error helpers
  formdata.ts       # multipart body builder for file uploads
  tools/
    health.ts collections.ts records.ts auth.ts superusers.ts
    files.ts logs.ts settings.ts backups.ts crons.ts raw.ts

npm run build     # tsc -> dist/
npm run watch     # tsc --watch
npm run dev       # run from TS via tsx (no build step)

Publicação (mantenedores)

O pacote é distribuído no npm e listado no MCP Registry oficial. Ambos são automatizados por .github/workflows/release.yml, acionados quando você publica uma GitHub Release.

Configuração única

• Crie um token de acesso Automation (ou granular, leitura+escrita) do npm e adicione-o como segredo do repositório NPM_TOKEN. (Mais tarde você pode migrar para Trusted Publishing / OIDC sem token e remover o segredo.)
• A etapa do MCP Registry usa GitHub OIDC (id-token: write) — nenhum segredo necessário. Ela publica sob o namespace io.github.nestebe/*, verificado pelo campo mcpName em package.json correspondente ao name em server.json.

Fazer um release

npm version patch          # or minor / major — bumps package.json + creates a git tag
# keep server.json "version" in sync with package.json, then commit it
git push --follow-tags
gh release create v1.0.0 --generate-notes   # publishing the release fires the workflow

O fluxo de trabalho então: compila → npm publish --provenance --access public → publica os metadados server.json no registro.

Publicação manual (sem CI)

npm publish --access public            # npm (must include the mcpName field)
# then, from the repo root:
mcp-publisher login github             # interactive GitHub OAuth (owner of "nestebe")
mcp-publisher publish                  # pushes server.json to registry.modelcontextprotocol.io

Antes de publicar, verifique o tarball e a saúde do pacote:

npm publish --dry-run     # inspect exactly what ships
npx publint               # lint package.json/exports/bin for publish issues

Licença

MIT © Nicolas ESTEBE