gridbase

gridbase

gridbase 是一个用于 Airtable 的工作台。它像人一样浏览一个 base：先列出令牌可访问的 base，再查看某个 base 中的表，以及每个表声明的字段和视图，最后查看记录——可以列出记录、按公式筛选、按文本搜索，也可以逐条获取。同一套功能也支持写入：可以创建、更新和删除记录，创建和重命名表及字段，还可以为记录添加评论并再次读取。一个二进制文件同时提供命令行界面和 stdio MCP 服务。

需要 Airtable 个人访问令牌。将其放入 AIRTABLE_API_KEY 环境变量；令牌会作为 Authorization: Bearer 标头发送给 API，不会出现在输出中。如果缺少该变量，每次调用都会在发出任何请求前失败，并报错指出该变量。令牌至少需要 schema.bases:read 和 data.records:read 权限范围，以及写入工具对应的写入权限范围。

安装

npx @reneturcios/gridbase bases

或者运行容器镜像：

docker run -i -e AIRTABLE_API_KEY ghcr.io/cloudcorprecords/gridbase

容器默认启动 MCP 服务（见下文）。传入 CLI 参数即可将其用作 CLI。

CLI

export AIRTABLE_API_KEY="pat..."

gridbase bases
gridbase tables appXXXXXXXXXXXXXX --detail full
gridbase describe appXXXXXXXXXXXXXX tblXXXXXXXXXXXXXX
gridbase records appXXXXXXXXXXXXXX tblXXXXXXXXXXXXXX --max 25 --filter "{Status}='Open'"
gridbase search appXXXXXXXXXXXXXX tblXXXXXXXXXXXXXX "quarterly report"
gridbase get appXXXXXXXXXXXXXX tblXXXXXXXXXXXXXX recXXXXXXXXXXXXXX
gridbase create appXXXXXXXXXXXXXX tblXXXXXXXXXXXXXX '{"Name":"New task","Status":"Open"}'
gridbase update appXXXXXXXXXXXXXX tblXXXXXXXXXXXXXX '[{"id":"recXXXXXXXXXXXXXX","fields":{"Status":"Done"}}]'
gridbase delete appXXXXXXXXXXXXXX tblXXXXXXXXXXXXXX recXXXXXXXXXXXXXX
gridbase create-table appXXXXXXXXXXXXXX Reports '[{"name":"Title","type":"singleLineText"}]'
gridbase comment appXXXXXXXXXXXXXX tblXXXXXXXXXXXXXX recXXXXXXXXXXXXXX "Looks good"
gridbase comments appXXXXXXXXXXXXXX tblXXXXXXXXXXXXXX recXXXXXXXXXXXXXX --page-size 10

gridbase --version

每条命令都会输出上游 JSON 负载。退出码：成功时为 0；调用失败时为 1（包括缺少 AIRTABLE_API_KEY 或 API 错误）；用法错误时为 2。

MCP 服务

同一个二进制文件提供两种用法。mcp 子命令会启动 stdio MCP 服务：

npx -y @reneturcios/gridbase mcp

MCP 客户端配置：

{
  "mcpServers": {
    "gridbase": {
      "command": "npx",
      "args": ["-y", "@reneturcios/gridbase", "mcp"],
      "env": { "AIRTABLE_API_KEY": "pat..." }
    }
  }
}

工具

工具	输入	返回内容
list_bases	（无）	所有可访问的 base，以及其 ID、名称和权限级别。
list_tables	baseId（必填）、detailLevel（可选）	base 中的表，按请求的详细级别精简。
describe_table	baseId、tableId（必填）、detailLevel（可选）	一个表的字段和视图。
list_records	baseId、tableId（必填）、maxRecords、filterByFormula（可选）	表中的记录。
search_records	baseId、tableId、searchTerm（必填）、fieldIds、maxRecords（可选）	字段值包含指定词语的记录。
get_record	baseId、tableId、recordId（必填）	单条记录。
create_record	baseId、tableId、fields（必填）	创建的记录。
update_records	baseId、tableId、records（必填）	更新后的记录。
delete_records	baseId、tableId、recordIds（必填）	每条记录对应的删除回执。
create_table	baseId、name、fields（必填）、description（可选）	创建的表。
update_table	baseId、tableId（必填）、name、description（可选）	更新后的表。
create_field	baseId、tableId、name、type（必填）、description、options（可选）	创建的字段。
update_field	baseId、tableId、fieldId（必填）、name、description（可选）	更新后的字段。
create_comment	baseId、tableId、recordId、text（必填）、parentCommentId（可选）	创建的评论。
list_comments	baseId、tableId、recordId（必填）、pageSize、offset（可选）	该记录的评论，按时间从新到旧排列。

Airtable 未提供文本搜索端点，因此 search_records 会列出表中的记录（数量受 maxRecords 限制），并保留字段值包含指定词语的记录；如果提供了 fieldIds，则只搜索指定字段。Schema 读取会自行精简 meta 负载：tableIdentifiersOnly 仅保留表 ID 和名称，identifiersOnly 还会将字段和视图精简为 ID 和名称，而 full（默认值）则返回所有内容。

开发

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev     # run the CLI from source via tsx

许可证

MIT — 参见 LICENSE。