Baserow Schema MCP

mcp-baserow-schema

Baserow 的 MCP 服务：一个支持 2FA 身份验证（TOTP）和 OpenAPI 验证的通用 Baserow API 客户端。

一个工具即可调用整个 Baserow REST API。可调用 OpenAPI 规范中记录的任何功能，包括架构变更（表、字段、视图、筛选器）、行的 CRUD 操作和工作区管理；JWT 身份验证会自动处理。

为什么

Baserow 官方 MCP 支持精选的数据 CRUD 操作，但不支持完整的 API 范围（架构变更、视图、筛选器、管理端点）。到了 2026 年，不支持 2FA 的纯密码身份验证已不可接受。此 MCP 同时解决了这两个问题：

• 完整的 API 访问权限：通过一个通用工具，调用随附的 Baserow OpenAPI 规范中的任意端点
• 支持 2FA：自动进行基于 TOTP 的身份验证，无需手动管理令牌
• OpenAPI 校验：请求会根据规范进行校验；路径拼写错误时会给出提示，而不是只返回令人困惑的 404
• 专为 Agent 设计：AI Agent 无需人工干预即可修改表结构

工具（2 个）

baserow_api

用于调用任意 Baserow API 端点的通用 HTTP 客户端。

参数	类型	说明
method	GET | POST | PATCH | DELETE | PUT	HTTP 方法
path	string	以 /api/ 开头的 API 路径
body	object, optional	POST/PATCH/PUT 请求的 JSON 请求体
query	object, optional	以字符串键值对形式传递的查询参数

示例：

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

身份验证会自动处理：只需提供 method、path，以及可选的 body/query。如果 OpenAPI 规范无法识别该路径或方法，响应开头会附带警告（⚠️ OpenAPI spec: ...），并列出相似路径；请求仍会执行（校验不会阻止请求）。

auth_status

返回当前身份验证状态：是否已通过身份验证、令牌过期时间，以及 access/refresh 令牌的剩余有效期。可用于调试身份验证生命周期。

OpenAPI 校验

服务随附官方 Baserow OpenAPI 规范（v2.2.2，共 275 个路径，仓库根目录下的 openapi.json）。每次请求前：

• 找到路径和方法 → 请求静默继续。
• 路径存在，但方法不匹配 → 警告会列出该路径可用的方法。
• 路径未知 → 警告中会附带规范中的最多 5 个相似路径。

规范会从 dist/../openapi.json 延迟加载；如果文件缺失，则会跳过校验并正常继续处理请求。

身份验证

支持 Baserow 的两步 2FA 流程：

1. POST /api/user/token-auth/ → 临时 2FA 令牌（约 60 s）
2. POST /api/two-factor-auth/verify/（使用 TOTP 代码）→ JWT access_token + refresh_token
3. POST /api/user/token-refresh/ → 静默获取新的 access_token（无需 2FA）

令牌生命周期：

• access_token：约 10 分钟（从 JWT 的 exp 声明中读取过期时间，并在过期前 2 分钟刷新）
• refresh_token：约 7 天（过期前 5 分钟重新进行完整的 2FA 登录）
• temp_token：约 60 秒（仅用于 2FA 验证步骤）

凭据通过环境变量传入，绝不会硬编码。

设置

前置条件

• Node.js ≥ 20
• 已启用 2FA 的 Baserow 账号
• Baserow TOTP 密钥（base32）

安装

git clone [email protected]:aficiomaquinas/mcp-baserow-schema.git
cd mcp-baserow-schema
npm install
npm run build

配置

设置环境变量（或使用 .env 文件，参见 .env.example）：

BASEROW_API_URL=https://your-baserow-instance.com
[email protected]
BASEROW_PASSWORD=your_password
BASEROW_TOTP_SECRET=YOUR_BASE32_TOTP_SECRET

Hermes Agent

添加到 ~/.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: [email protected]
      BASEROW_PASSWORD: your_password
      BASEROW_TOTP_SECRET: YOUR_BASE32_TOTP_SECRET

Claude Desktop

添加到 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": "[email protected]",
        "BASEROW_PASSWORD": "your_password",
        "BASEROW_TOTP_SECRET": "YOUR_BASE32_TOTP_SECRET"
      }
    }
  }
}

字段类型

由于 baserow_api 是透传客户端，因此支持所有 Baserow 字段类型；只需确保 JSON 请求体符合相应端点的 API 契约。字段类型参考列表：

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

端点详情：请查阅随附的 openapi.json 或 Baserow API 文档。

与官方 Baserow MCP 配合使用

从 v2 开始，此 MCP 也涵盖数据操作（行、批次、搜索、排序），因此官方 Baserow MCP 并非必需：

• mcp-baserow-schema → 涵盖所有内容：架构、数据、视图、筛选器、管理
• 官方 Baserow MCP → 精选的行 CRUD 体验，如果你更喜欢用它处理数据

两者同时运行没有问题；它们不会冲突。

发布

维护者：请参阅 docs/RELEASING.md。发布流程已完全自动化（release-it + 使用 OIDC 可信发布的 GitHub Actions）——切勿手动更新版本号、标签或 server.json。

许可证

MIT