mcp-baserow-schema

mcp-baserow-schema

Servidor MCP para Baserow: un cliente genérico de la API de Baserow con autenticación 2FA (TOTP) y validación OpenAPI.

Una herramienta, toda la API REST de Baserow. Cambios de esquema (tablas, campos, vistas, filtros), CRUD de filas, administración de espacios de trabajo — cualquier cosa documentada en la especificación OpenAPI es invocable, con autenticación JWT manejada automáticamente.

Por qué

El MCP oficial de Baserow maneja CRUD de datos seleccionado, pero no toda la superficie de la API (cambios de esquema, vistas, filtros, endpoints de administración). En 2026, la autenticación simple con contraseña sin 2FA no es aceptable. Este MCP resuelve ambos:

• Acceso completo a la API: cualquier endpoint de la especificación OpenAPI de Baserow incluida a través de una herramienta genérica
• Soporte 2FA: autenticación automática basada en TOTP — sin gestión manual de tokens
• Protección OpenAPI: las solicitudes se validan contra la especificación; las rutas mal escritas reciben una pista en lugar de un 404 misterioso
• Diseñado para agentes: los agentes de IA pueden modificar la estructura de tablas sin intervención humana

Herramientas (2)

baserow_api

Cliente HTTP genérico para cualquier endpoint de la API de Baserow.

Parámetro	Tipo	Descripción
method	GET | POST | PATCH | DELETE | PUT	Método HTTP
path	string	Ruta de la API que comienza con /api/
body	object, opcional	Cuerpo JSON para POST/PATCH/PUT
query	object, opcional	Parámetros de consulta como pares clave-valor de cadena

Ejemplos:

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

La autenticación se maneja automáticamente: solo proporciona método, ruta y cuerpo/consulta opcionales. Si la especificación OpenAPI no reconoce la ruta/método, la respuesta se prefija con una advertencia (⚠️ OpenAPI spec: ...) que incluye rutas similares — la solicitud aún se ejecuta (la validación no es bloqueante).

auth_status

Devuelve el estado de autenticación actual: autenticado, expiración del token y vida restante de los tokens de acceso/refresco. Útil para depurar el ciclo de vida de la autenticación.

Validación OpenAPI

El servidor incluye la especificación OpenAPI oficial de Baserow (v2.2.2, 275 rutas, openapi.json en la raíz del repositorio). Antes de cada solicitud:

• Ruta + método encontrados → la solicitud procede silenciosamente.
• Ruta existe, método incorrecto → la advertencia lista los métodos disponibles para esa ruta.
• Ruta desconocida → advertencia más hasta 5 rutas similares de la especificación.

La especificación se carga de forma diferida desde dist/../openapi.json; si falta, la validación se omite con elegancia y las solicitudes proceden sin validar.

Autenticación

Soporta el flujo 2FA de dos pasos de Baserow:

1. POST /api/user/token-auth/ → token 2FA temporal (~60 s)
2. POST /api/two-factor-auth/verify/ (con código TOTP) → access_token + refresh_token JWT
3. POST /api/user/token-refresh/ → nuevo access_token, silenciosamente (sin necesidad de 2FA)

Ciclo de vida del token:

• access_token: ~10 minutos (expiración leída de la reclamación exp del JWT, renovado 2 minutos antes de la expiración)
• refresh_token: ~7 días (re-inicio de sesión 2FA completo 5 minutos antes de la expiración)
• temp_token: ~60 segundos (solo para el paso de verificación 2FA)

Las credenciales se pasan a través de variables de entorno — nunca codificadas.

Configuración

Requisitos previos

• Node.js ≥ 20
• Cuenta de Baserow con 2FA habilitado
• Secreto TOTP de Baserow (base32)

Instalación

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

Configurar

Establece variables de entorno (o usa un archivo .env — ver .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

Agrega 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

Agrega 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

Dado que baserow_api es un cliente de paso directo, cada tipo de campo de Baserow es compatible — el cuerpo JSON solo necesita coincidir con el contrato de la API para el endpoint. Lista de referencia de 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

Detalles de endpoints: consulta el openapi.json incluido o la documentación de la API de Baserow.

Uso con el MCP oficial de Baserow

Desde la v2, este MCP también cubre operaciones de datos (filas, lotes, búsqueda, ordenación), por lo que el MCP oficial de Baserow es opcional:

• mcp-baserow-schema → todo: esquema, datos, vistas, filtros, administración
• MCP oficial de Baserow → UX de CRUD de filas seleccionado, si lo prefieres para trabajo de datos

Ejecutar ambos en paralelo está bien; no entran en conflicto.

Publicación

Mantenedores: ver docs/RELEASING.md. Las publicaciones están totalmente automatizadas (release-it + GitHub Actions con publicación confiable OIDC) — nunca cambies versiones, etiquetas o server.json manualmente.

Licencia

MIT