SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场airtable-cli

airtable-cli

数据与分析

查看项目

更新于 10-16 08:26

技能介绍

用途

airtable-cli 是 Airtable 提供的命令行工具，安装包名为 @airtable/mcp-cli，可执行命令为 airtable-mcp。它用于在终端中通过 MCP 服务器操作 Airtable，包括列出 bases、读取和写入记录、管理表和字段、过滤和搜索数据。工具列表在运行时从 MCP 服务器动态获取，CLI 本身不维护硬编码的命令清单，因此工具名称、参数和输出结构可能随服务器版本变化。

主要能力

  • 自发现：通过 airtable-mcp tools 列出可用工具，--json 输出机器可解析的 {name, title, access} 数组，<tool> --help 查看具体参数。
  • 凭据管理：支持环境变量 AIRTABLE_TOKEN，或通过 airtable-mcp configure 交互式配置（令牌保存在 ~/.airtable/cli.json，权限 0600）；支持命名 profile、whoami 检查状态、logout 登出（--all 清除全部）。
  • 数据操作：可搜索 bases、列出表、按字段列出记录、使用结构化 JSON 过滤器筛选记录、全文搜索记录、批量更新记录等。
  • 输出与自动化：默认输出格式化 JSON 到 stdout，状态信息到 stderr；支持 --json、--output raw、--input -（从 stdin 读取 JSON 参数）、-q/--quiet、--refresh 绕过工具缓存、--profile 指定配置。退出码 0 成功、1 错误、2 用法错误。

使用方式

安装：npm install -g @airtable/mcp-cli

认证：export AIRTABLE_TOKEN=pat_xxx，或运行 airtable-mcp configure。令牌需在 https://airtable.com/create/tokens 创建，并具备所调用工具所需的 scopes。未指定 --profile 时，AIRTABLE_TOKEN 优先于已保存的 profile。

典型流程：认证 → airtable-mcp tools 发现工具 → <tool> --help 查看参数 → 在 tools --json 输出中检查 access 字段（read-only、write 或 destructive），执行破坏性工具前与用户确认 → 执行 airtable-mcp <tool> --flagName value。

CLI 中工具名使用连字符（如 list-records），MCP 中使用下划线（如 list_records），CLI 会自动转换。

常见任务示例：

查找 base 并列出表： airtable-mcp search-bases --searchQuery "Project Tracker" -q airtable-mcp list-tables-for-base --baseId appK9MtBqFw3o5jGN -q

列出指定字段的记录： airtable-mcp list-records-for-table --baseId appK9MtBqFw3o5jGN --tableId tblL4GpTfEz8byRsW --fieldIds '["Name","Status"]' --pageSize 10 -q

过滤记录（使用结构化 JSON，而非公式字符串；条件放在 operands 数组中，顶层 operator 省略时默认为 and）： airtable-mcp list-records-for-table --baseId appK9MtBqFw3o5jGN --tableId tblL4GpTfEz8byRsW --filters '{"operator":"and","operands":[{"operator":"=","operands":["Status","Done"]}]}' -q

搜索记录（适合大表的自由文本/模糊查询）： airtable-mcp search-records --baseId appK9MtBqFw3o5jGN --table tblL4GpTfEz8byRsW --query "acme" --fields '["Name","Notes"]' -q

更新记录（复杂参数建议用 --input -）： echo '{"baseId":"appK9MtBqFw3o5jGN","tableId":"tblL4GpTfEz8byRsW","records":[{"id":"recVnR3xPq8sD2yLk","fields":{"fld8WsrpLHHevsnW8":"Done"}}]}' | airtable-mcp update-records-for-table --input - -q

适用场景

适合需要在脚本、自动化流程或智能体（agent）中程序化操作 Airtable 数据的用户，例如批量读写记录、按条件筛选数据、跨 base 检索信息等。

限制与注意事项

  • 工具名不存在或缓存过期时，运行 airtable-mcp tools --refresh 刷新后重试。
  • 认证失败通常因令牌过期、撤销或错误，需重新 configure 或检查 AIRTABLE_TOKEN。
  • 访问被拒通常因令牌缺少所需 scopes，需在令牌创建页面补充。
  • 连接超时（10 秒）时检查网络；CLI 在可用时会回退到过期缓存。
  • 布尔标志不接收值，使用 --dryRun 而非 --dryRun true。
  • 数组/对象参数必须是合法 JSON 字符串。
  • 单个过滤条件需包裹在 {"operands":[...]} 中，否则顶层会被拒绝。
  • 排序键使用 fieldId 而非 field，如 {"fieldId":"Name","direction":"asc"}，接受字段 ID 或名称。
  • select 字段过滤需使用 choice ID（来自 get-table-schema），而非显示名称；写入时 select 值需用纯字符串，读取时返回对象 {"id":"sel...","name":"Done"}。
  • 创建/更新记录时字段键目前需要字段 ID（fldXXX），需先用 get-table-schema 将名称解析为 ID；而 fieldIds、sort、filters 同时接受名称和 ID。
  • 批量写入默认每请求上限 10 条记录（因账户而异），超出会报 INVALID_RECORDS，需分块并查看 <tool> --help 确认当前限制。
  • 若用户对 base 仅有 interface-only 访问权限，list-records-for-table 会报权限错误，应改用 list-records-for-page / get-record-for-page。
  • CLI 仅允许访问 *.airtable.com 的 HTTPS 端点，不能指向任意服务器（安全约束）。
  • 切勿记录或回显令牌。