mcp-baserow-schema

mcp-baserow-schema

Servidor MCP para Baserow: um cliente genérico da API Baserow com autenticação 2FA (TOTP) e validação OpenAPI.

Uma ferramenta, toda a API REST do Baserow. Alterações de esquema (tabelas, campos, visualizações, filtros), CRUD de linhas, administração de workspace — qualquer coisa documentada na especificação OpenAPI é acionável, com autenticação JWT tratada automaticamente.

Por quê

O MCP oficial do Baserow lida com CRUD de dados selecionado, mas não com toda a superfície da API (alterações de esquema, visualizações, filtros, endpoints administrativos). Em 2026, autenticação simples por senha sem 2FA não é aceitável. Este MCP resolve ambos:

• Acesso completo à API: qualquer endpoint da especificação OpenAPI do Baserow incluída, por meio de uma ferramenta genérica
• Suporte a 2FA: autenticação automática baseada em TOTP — sem gerenciamento manual de tokens
• Proteção OpenAPI: requisições são validadas contra a especificação; caminhos digitados incorretamente recebem uma dica em vez de um 404 misterioso
• Projetado para agentes: agentes de IA podem modificar a estrutura de tabelas sem intervenção humana

Ferramentas (2)

baserow_api

Cliente HTTP genérico para qualquer endpoint da API Baserow.

Parâmetro	Tipo	Descrição
method	GET | POST | PATCH | DELETE | PUT	Método HTTP
path	string	Caminho da API começando com /api/
body	objeto, opcional	Corpo JSON para POST/PATCH/PUT
query	objeto, opcional	Parâmetros de consulta como pares chave-valor de string

Exemplos:

GET    /api/database/tables/database/123/                    → list tables in database 123
POST   /api/database/views/table/456/       {name, type}     → create view
POST   /api/database/views/789/filters/     {field, type, value} → create filter
DELETE /api/database/tables/456/                             → delete table
PATCH  /api/database/rows/table/456/11/    {status}   ?user_field_names=true → update row
POST   /api/database/rows/table/456/batch/ {items:[...]}      → batch update

A autenticação é tratada automaticamente: basta fornecer método, caminho e corpo/consulta opcionais. Se a especificação OpenAPI não reconhecer o caminho/método, a resposta é prefixada com um aviso (⚠️ OpenAPI spec: ...) incluindo caminhos semelhantes — a requisição ainda é executada (a validação não é bloqueante).

auth_status

Retorna o estado atual de autenticação: autenticado, expiração do token e tempo de vida restante dos tokens de acesso/atualização. Útil para depurar o ciclo de vida da autenticação.

Validação OpenAPI

O servidor inclui a especificação OpenAPI oficial do Baserow (v2.2.2, 275 caminhos, openapi.json na raiz do repositório). Antes de cada requisição:

• Caminho + método encontrados → a requisição prossegue silenciosamente.
• Caminho existe, método errado → o aviso lista os métodos disponíveis para aquele caminho.
• Caminho desconhecido → aviso mais até 5 caminhos semelhantes da especificação.

A especificação é carregada lentamente de dist/../openapi.json; se ausente, a validação é ignorada graciosamente e as requisições prosseguem sem validação.

Autenticação

Suporta o fluxo de 2FA em duas etapas do Baserow:

1. POST /api/user/token-auth/ → token 2FA temporário (~60 s)
2. POST /api/two-factor-auth/verify/ (com código TOTP) → access_token JWT + refresh_token
3. POST /api/user/token-refresh/ → novo access_token, silenciosamente (sem necessidade de 2FA)

Ciclo de vida do token:

• access_token: ~10 minutos (expiração lida da claim exp do JWT, renovado 2 minutos antes da expiração)
• refresh_token: ~7 dias (re-login completo com 2FA 5 minutos antes da expiração)
• temp_token: ~60 segundos (apenas para a etapa de verificação 2FA)

As credenciais são passadas por variáveis de ambiente — nunca codificadas.

Configuração

Pré-requisitos

• Node.js ≥ 20
• Conta Baserow com 2FA habilitado
• Segredo TOTP do Baserow (base32)

Instalação

git clone git@github.com:aficiomaquinas/mcp-baserow-schema.git
cd mcp-baserow-schema
npm install
npm run build

Configuração

Defina variáveis de ambiente (ou use um arquivo .env — veja .env.example):

BASEROW_API_URL=https://your-baserow-instance.com
BASEROW_USERNAME=you@example.com
BASEROW_PASSWORD=your_password
BASEROW_TOTP_SECRET=YOUR_BASE32_TOTP_SECRET

Hermes Agent

Adicione a ~/.hermes/profiles/<profile>/config.yaml:

mcp_servers:
  baserow-mcp:
    command: node
    args:
      - /path/to/mcp-baserow-schema/dist/index.js
    enabled: true
    env:
      BASEROW_API_URL: https://baserow.example.com
      BASEROW_USERNAME: you@example.com
      BASEROW_PASSWORD: your_password
      BASEROW_TOTP_SECRET: YOUR_BASE32_TOTP_SECRET

Claude Desktop

Adicione a claude_desktop_config.json:

{
  "mcpServers": {
    "baserow-schema": {
      "command": "node",
      "args": ["/path/to/mcp-baserow-schema/dist/index.js"],
      "env": {
        "BASEROW_API_URL": "https://baserow.example.com",
        "BASEROW_USERNAME": "you@example.com",
        "BASEROW_PASSWORD": "your_password",
        "BASEROW_TOTP_SECRET": "YOUR_BASE32_TOTP_SECRET"
      }
    }
  }
}

Tipos de Campo

Como baserow_api é um cliente de passagem, todos os tipos de campo do Baserow são suportados — o corpo JSON só precisa corresponder ao contrato da API para o endpoint. Lista de referência dos tipos de campo:

text, long_text, url, email, number, rating, boolean, date, last_modified, last_modified_by, created_on, created_by, duration, link_row, file, single_select, multiple_select, phone_number, formula, count, rollup, lookup, multiple_collaborators, uuid, autonumber, password, ai

Detalhes dos endpoints: consulte o openapi.json incluído ou a documentação da API Baserow.

Uso com o MCP Oficial do Baserow

Desde a v2, este MCP também cobre operações de dados (linhas, lotes, busca, ordenação), então o MCP oficial do Baserow é opcional:

• mcp-baserow-schema → tudo: esquema, dados, visualizações, filtros, administração
• MCP oficial do Baserow → UX selecionada de CRUD de linhas, se você preferir para trabalho com dados

Executar ambos lado a lado é aceitável; eles não conflitam.

Lançamento

Mantenedores: veja docs/RELEASING.md. Os lançamentos são totalmente automatizados (release-it + GitHub Actions com publicação confiável via OIDC) — nunca altere versões, tags ou server.json manualmente.

Licença

MIT