Pocketbase

pocketbase-mcp

Servidor MCP remoto que conecta qualquer cliente MCP a uma instância PocketBase via HTTP sem estado.

Início rápido

Use a instância hospedada em https://pocketbase.tokenscompany.co/mcp ou hospede a sua própria.

Instalar com agente de IA

Copie e cole este prompt no seu agente de IA (Claude Code, Cursor, Windsurf, etc.):

Install the PocketBase MCP server. The MCP endpoint is https://pocketbase.tokenscompany.co/mcp and the transport type is http (NOT sse). It requires X-PB-URL set to my PocketBase instance URL and either X-PB-Email + X-PB-Password (superuser credentials) or X-PB-Token (superuser auth token). Add it to my project MCP config with type "http". Then fetch https://raw.githubusercontent.com/tokenscompany/pocketbase-mcp/main/SKILL.md and save it to my project's agent instructions so you always know how to use the PocketBase tools.

claude mcp add --transport http pocketbase https://pocketbase.tokenscompany.co/mcp \
  --header "X-PB-URL: https://your-pocketbase.example.com" \
  --header "X-PB-Email: admin@example.com" \
  --header "X-PB-Password: your-password"

{
  "mcpServers": {
    "pocketbase": {
      "type": "http",
      "url": "https://pocketbase.tokenscompany.co/mcp",
      "headers": {
        "X-PB-URL": "${PB_URL}",
        "X-PB-Email": "${PB_EMAIL}",
        "X-PB-Password": "${PB_PASSWORD}"
      }
    }
  }
}

{
  "mcpServers": {
    "pocketbase": {
      "url": "https://pocketbase.tokenscompany.co/mcp",
      "headers": {
        "X-PB-URL": "https://your-pocketbase.example.com",
        "X-PB-Email": "admin@example.com",
        "X-PB-Password": "your-password"
      }
    }
  }
}

{
  "mcp": {
    "pocketbase": {
      "type": "remote",
      "url": "https://pocketbase.tokenscompany.co/mcp",
      "headers": {
        "X-PB-URL": "https://your-pocketbase.example.com",
        "X-PB-Email": "admin@example.com",
        "X-PB-Password": "your-password"
      },
      "enabled": true
    }
  }
}

Auto-hospedagem

Bun

bun install
bun run src/index.ts

O servidor escuta em PORT (padrão 3000).

Docker (GHCR)

docker pull ghcr.io/tokenscompany/pocketbase-mcp:latest
docker run -p 3000:3000 ghcr.io/tokenscompany/pocketbase-mcp:latest

Ou construa localmente:

docker build -t pocketbase-mcp .
docker run -p 3000:3000 pocketbase-mcp

Verificando a imagem

Toda imagem publicada no GHCR inclui atestado de proveniência SLSA. Você pode verificar se uma imagem foi construída a partir deste repositório:

gh attestation verify oci://ghcr.io/tokenscompany/pocketbase-mcp:latest \
  --owner tokenscompany

Autenticação

Toda requisição ao POST /mcp deve incluir X-PB-URL e um dos dois métodos de autenticação:

Opção 1: E-mail + Senha (recomendado)

O servidor autentica contra o PocketBase em cada requisição. Nenhum gerenciamento manual de token é necessário.

Opção 2: Token

Para obter um token manualmente:

curl -X POST https://your-pb.example.com/api/admins/auth-with-password \
  -H 'Content-Type: application/json' \
  -d '{"identity":"admin@example.com","password":"your-password"}'

O campo token na resposta é o seu X-PB-Token. Se tanto o token quanto e-mail+senha forem fornecidos, o token tem prioridade.

Ferramentas

Recursos

Segurança e Privacidade

Este servidor é totalmente sem estado — ele não armazena, registra ou retém nenhum dos seus dados:

• Sem banco de dados, sem gravação em disco — cada requisição cria um novo servidor MCP e transporte em memória, processa e descarta tudo. Nada é gravado em disco.
• Sem armazenamento de credenciais — seus cabeçalhos X-PB-URL, X-PB-Token, X-PB-Email e X-PB-Password são usados durante a requisição e nunca são persistidos, armazenados em cache ou registrados.
• Sem telemetria ou analytics — o servidor coleta zero dados de uso. Nenhum serviço de terceiros é contatado.
• Sem sessões — não há cookies, IDs de sessão ou estado no lado do servidor entre requisições.
• Código aberto — toda a base de código é licenciada sob MIT. Cada imagem Docker inclui atestado de proveniência SLSA, para que você possa verificar que foi construída diretamente deste repositório sem modificações.
• Hospede você mesmo — para máximo controle, execute sua própria instância. O servidor é um único contêiner sem dependências externas além da sua instância PocketBase.

Endurecimento

Ao hospedar uma instância pública, o servidor inclui várias medidas adicionais:

• Proteção SSRF — X-PB-URL é validado: apenas esquemas http/https são permitidos, e nomes de host que resolvem para faixas de IP privadas/reservadas (127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16, ::1, fc00::/7, fe80::/10) são rejeitados.

• Limitação de taxa — token-bucket em memória por IP. Configurável via variáveis de ambiente:

  Variável	Padrão	Descrição
  RATE_LIMIT_RPM	60	Requisições por minuto por IP
  RATE_LIMIT_BURST	10	Tamanho máximo de rajada

• CORS — Access-Control-Allow-Origin: * com suporte a preflight em /mcp.

• Limite de tamanho do corpo — requisições maiores que 1 MB são rejeitadas com 413.

Endpoints

Solução de problemas

Erro "Failed to reconnect"

A configuração do seu cliente MCP provavelmente usa "type": "sse". Este servidor usa HTTP streamable sem estado, não Server-Sent Events. Altere o tipo de transporte para "http":

{
  "mcpServers": {
    "pocketbase": {
      "type": "http",
      ...
    }
  }
}

Para a CLI do Claude Code, use --transport http ao adicionar:

claude mcp add --transport http pocketbase https://pocketbase.tokenscompany.co/mcp ...

Licença

MIT