mcpField
A
airtable-cli

airtable-cli

github.com/airtable数据与数据库53257 次安装14 周前更新
代码仓库

关于 airtable-cli

airtable-cli 是用于发现和调用 Airtable MCP 服务工具的命令行客户端，适合脚本和 Agent 使用。它支持令牌认证、命名配置及结构化输入输出。

主要功能

  1. 01运行时发现工具
  2. 02通过命令行调用 MCP 工具
  3. 03配置令牌和命名配置
  4. 04通过标准输入传入 JSON 参数
  5. 05选择 JSON 或原始输出

适用场景

  1. 01查看 Airtable 服务提供的工具
  2. 02搜索 Base 并读取表格记录
  3. 03按字段筛选或搜索记录
  4. 04在脚本中创建或更新记录

MCP 相关

命令行会在运行时从 Airtable MCP 服务获取工具列表并调用工具，并将命令行中的连字符名称转换为 MCP 下划线名称。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/airtable/skills --skill airtable-cli

安装后在 Claude Code 中输入/airtable-cli确认已加载。

详细介绍

airtable-mcp

自发现

运行时会从 MCP 服务获取工具，因此 CLI 不会硬编码命令列表。查看有哪些可用工具：

airtable-mcp tools            # human-readable list
airtable-mcp tools --json     # machine-parseable list
airtable-mcp <tool> --help    # show flags and descriptions for a tool

在假设某个工具存在之前，先运行 airtable-mcp tools。工具名称、参数和输出格式可能会随服务版本更新而变化，无需更新 CLI。

安装

npm install -g @airtable/mcp-cli

身份验证

CLI 需要 Airtable 个人访问令牌（PAT）。有两种方式：

环境变量（推荐用于脚本和 Agent）：

export AIRTABLE_TOKEN=pat_xxx

交互式配置（以 0600 权限将令牌存储在 ~/.airtable/cli.json 中）：

airtable-mcp configure

在 https://airtable.com/create/tokens 创建令牌。确保令牌具有所调用工具所需的范围。

未设置 --profile 标志时，AIRTABLE_TOKEN 的优先级高于已保存的配置。切勿记录或回显令牌。

快速参考

任务命令
设置凭据airtable-mcp configure
添加命名配置airtable-mcp configure --profile work
检查身份验证状态airtable-mcp whoami
移除凭据airtable-mcp logout
移除所有配置airtable-mcp logout --all
列出可用工具airtable-mcp tools
运行工具airtable-mcp <tool> --flagName value
查看工具帮助airtable-mcp <tool> --help
通过 stdin 传递参数echo '{"key":"val"}' | airtable-mcp <tool> --input -
绕过工具缓存airtable-mcp <tool> --refresh
禁止显示状态消息airtable-mcp <tool> -q
输出原始文本airtable-mcp <tool> --output raw
使用指定配置airtable-mcp <tool> --profile work

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

工作流

  1. 身份验证 — 设置 AIRTABLE_TOKEN 或运行 airtable-mcp configure
  2. 发现 — 运行 airtable-mcp tools 查看可用工具
  3. 检查 — 运行 airtable-mcp <tool> --help 查看标志和说明
  4. 检查访问权限 — 在 tools --json 的输出中查看 access 字段：read-only、write 或 destructive。运行 destructive 工具前，请先与用户确认。
  5. 执行 — 运行 airtable-mcp <tool> --flagName value

输出与自动化

  • 默认输出为格式化的 JSON，并写入 stdout。状态消息会写入 stderr。
  • 对 tools 使用 --json 会返回包含 {name, title, access} 的 JSON 数组。
  • -q / --quiet 会禁止显示 stderr 状态消息（缓存警告等）。
  • --output raw 会返回服务端的原始响应文本，而不是解析后的 JSON。
  • --input - 会从 stdin 读取 JSON 对象形式的工具参数，并跳过标志解析。
  • 退出代码：0 表示成功，1 表示错误（身份验证失败、工具执行失败、未找到），2 表示用法错误（标志错误、输入错误）。

常见任务

查找一个 base 并列出其表：

airtable-mcp search-bases --searchQuery "Project Tracker" -q
airtable-mcp list-tables-for-base --baseId appEXAMPLEbase001 -q

使用指定字段列出记录：

airtable-mcp list-records-for-table \
  --baseId appEXAMPLEbase001 --tableId tblEXAMPLEtable01 \
  --fieldIds '["Name","Status"]' --pageSize 10 -q

筛选记录 — 筛选条件使用结构化 JSON，而非公式字符串。将条件放入 operands 数组；如果省略顶层 operator，则默认为 and：

airtable-mcp list-records-for-table \
  --baseId appEXAMPLEbase001 --tableId tblEXAMPLEtable01 \
  --filters '{"operator":"and","operands":[{"operator":"=","operands":["Status","Done"]}]}' -q

对于 select 字段，请按选项 ID（来自 get-table-schema）筛选，而不是按显示名称筛选。airtable-filters 技能涵盖复合筛选、日期筛选，以及按操作符和字段类型划分的详细信息。

搜索记录 — 对大型表进行自由文本／模糊查询时，请使用 search-records。按精确字段值筛选时，请使用 list-records-for-table 和 --filters：

airtable-mcp search-records \
  --baseId appEXAMPLEbase001 --table tblEXAMPLEtable01 \
  --query "acme" --fields '["Name","Notes"]' -q

传入 --fields ALL_SEARCHABLE_FIELDS，即可搜索所有已索引字段。日期、评分、复选框和按钮字段不可搜索。

更新记录 — 使用 --input - 传入复杂参数会更方便：

echo '{"baseId":"appEXAMPLEbase001","tableId":"tblEXAMPLEtable01","records":[{"id":"recEXAMPLErecord1","fields":{"fldEXAMPLEfield01":"Done"}}]}' \
  | airtable-mcp update-records-for-table --input - -q

select 字段值以对象形式返回（{"id":"sel...","name":"Done"}），但写入时必须使用纯字符串（"Done"）。创建／更新时，记录字段的键目前必须使用字段 ID（fldEXAMPLEfield02）——写入前请使用 get-table-schema 将名称解析为 ID。请注意，fieldIds、sort 和 filters 同时接受名称和 ID。

注意事项

问题原因解决方法
Unknown tool: X服务上不存在该工具名称，或缓存已过期运行 airtable-mcp tools --refresh 刷新，然后重试
Authentication failed令牌已过期、已撤销或不正确运行 airtable-mcp configure 或检查 AIRTABLE_TOKEN
Access denied令牌缺少所需的作用域在 https://airtable.com/create/tokens 添加作用域
Connection timed out服务不可达（超时为 10s）检查网络；如果有可用的旧缓存，CLI 会回退到该缓存
布尔标志不接受值--dryRun true 会将 "true" 作为下一个参数传入单独使用 --dryRun（布尔值根据是否存在来判断）
数组／对象参数失败值不是有效的 JSON以 JSON 字符串传入：--fieldMappings '{"a":"b"}'
顶层筛选条件被拒绝单个条件未使用 operands 包装使用 {"operands":[...]} 包装（operator 默认为 and）
排序键是 fieldId，而不是 field--sort '[{"field":"Name"}]' 会被静默忽略使用 {"fieldId":"Name","direction":"asc"} — 接受字段 ID 或名称
Select 筛选结果为空按显示名称筛选，而不是按选项 ID 筛选先运行 get-table-schema 获取 sel... 选项 ID
批量写入时出现 INVALID_RECORDS每次请求的批次上限为 10 条记录（默认值；因账户而异）分成每批 ≤10 条，并通过 <tool> --help 查看当前上限
list-records-for-table 出现权限错误用户对该 base 只有界面访问权限改用 list-records-for-page / get-record-for-page
端点受限CLI 仅允许使用 *.airtable.com 上的 HTTPS无法指向任意服务（安全限制）

评论

支持 Markdown