Back to Details

airtable-cli

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

airtable-mcp

airtable-mcp

Self-discovery

工具自动发现

Tools are fetched from the MCP server at runtime, so the CLI never has a hardcoded command list. Discover what's available:
sh
airtable-mcp tools            # human-readable list
airtable-mcp tools --json     # machine-parseable list
airtable-mcp <tool> --help    # show flags and descriptions for a tool
Run 
airtable-mcp tools
before assuming a tool exists. Tool names, arguments, and output shapes can change between server releases without a CLI update.
工具会在运行时从MCP服务器获取，因此CLI从未内置硬编码的命令列表。可通过以下方式查看可用工具：
sh
airtable-mcp tools            # 人类可读格式的列表
airtable-mcp tools --json     # 机器可解析格式的列表
airtable-mcp <tool> --help    # 查看工具的参数和说明
在假设某个工具存在前，请先运行
airtable-mcp tools
。工具名称、参数和输出格式可能会随服务器版本更新而变化，无需同步更新CLI。

Install

安装

sh
npm install -g @airtable/mcp-cli
sh
npm install -g @airtable/mcp-cli

Auth

身份验证

The CLI needs an Airtable personal access token (PAT). Two paths:
Environment variable (preferred for scripts/agents):
sh
export AIRTABLE_TOKEN=pat_xxx
Interactive configure (stores token in 
~/.airtable/cli.json
with 0600 permissions):
sh
airtable-mcp configure
Create tokens at https://airtable.com/create/tokens. Ensure the token has the scopes required by the tools being called.
AIRTABLE_TOKEN
takes precedence over saved profiles when no 
--profile
flag is set. Never log or echo tokens.
CLI需要Airtable个人访问令牌（PAT）。有两种配置方式：
环境变量（脚本/Agent优先选择）：
sh
export AIRTABLE_TOKEN=pat_xxx
交互式配置（令牌将存储在
~/.airtable/cli.json
中，权限为0600）：
sh
airtable-mcp configure
可在https://airtable.com/create/tokens创建令牌。确保令牌拥有调用工具所需的权限范围。 当未设置
--profile
参数时，
AIRTABLE_TOKEN
的优先级高于已保存的配置文件。切勿记录或回显令牌。

Quick reference

快速参考

TaskCommand
Set up credentials
airtable-mcp configure
Add a named profile
airtable-mcp configure --profile work
Check auth status
airtable-mcp whoami
Remove credentials
airtable-mcp logout
Remove all profiles
airtable-mcp logout --all
List available tools
airtable-mcp tools
Run a tool
airtable-mcp <tool> --flagName value
Get tool help
airtable-mcp <tool> --help
Pass args via stdin
echo '{"key":"val"}' | airtable-mcp <tool> --input -
Bypass tool cache
airtable-mcp <tool> --refresh
Suppress status msgs
airtable-mcp <tool> -q
Raw text output
airtable-mcp <tool> --output raw
Use a specific profile
airtable-mcp <tool> --profile work
Tool names use hyphens on the CLI (
list-records
) but underscores in MCP (
list_records
). The CLI translates automatically.
任务命令
设置凭证
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
通过标准输入传递参数
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会自动进行转换。

Workflow

工作流程

  1. Auth — set 
    AIRTABLE_TOKEN
    or run 
    airtable-mcp configure
  2. Discover — run 
    airtable-mcp tools
    to see available tools
  3. Inspect — run 
    airtable-mcp <tool> --help
    for flags and descriptions
  4. Check access — in 
    tools --json
    output, check the 
    access
    field: 
    read-only
    , 
    write
    , or 
    destructive
    . Confirm with the user before running 
    destructive
    tools.
  5. Execute — run 
    airtable-mcp <tool> --flagName value
  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

Output & automation

输出与自动化

  • Default output is formatted JSON to stdout. Status messages go to stderr.
  • --json
    on 
    tools
    gives a JSON array of 
    {name, title, access}
    .
  • -q
    / 
    --quiet
    suppresses stderr status messages (cache warnings, etc).
  • --output raw
    returns the raw server response text instead of parsed JSON.
  • --input -
    reads tool arguments as a JSON object from stdin, bypassing flag parsing.
  • Exit codes: 
    0
    success, 
    1
    error (auth, tool failure, not found), 
    2
    usage error (bad flags, bad input).
  • 默认输出为格式化JSON至标准输出，状态消息输出至标准错误流。
  • 在
    tools
    命令后添加
    --json
    会返回包含
    {name, title, access}
    的JSON数组。
  • -q
    / 
    --quiet
    参数会抑制标准错误流中的状态消息（如缓存警告等）。
  • --output raw
    参数会返回服务器原始响应文本，而非解析后的JSON。
  • --input -
    参数会从标准输入读取工具参数（JSON对象），绕过参数解析。
  • 退出码：
    0
    表示成功，
    1
    表示错误（身份验证失败、工具执行失败、工具未找到），
    2
    表示使用错误（参数无效、输入错误）。

Common tasks

常见任务

Find a base and list its tables:
sh
airtable-mcp search-bases --searchQuery "Project Tracker" -q
airtable-mcp list-tables-for-base --baseId appEXAMPLEbase001 -q
List records with specific fields:
sh
airtable-mcp list-records-for-table \
  --baseId appEXAMPLEbase001 --tableId tblEXAMPLEtable01 \
  --fieldIds '["Name","Status"]' --pageSize 10 -q
Filter records — filters use structured JSON, not formula strings. Wrap conditions in an 
operands
array; the top-level 
operator
defaults to 
and
if omitted:
sh
airtable-mcp list-records-for-table \
  --baseId appEXAMPLEbase001 --tableId tblEXAMPLEtable01 \
  --filters '{"operator":"and","operands":[{"operator":"=","operands":["Status","Done"]}]}' -q
For select fields, filter by choice ID (from 
get-table-schema
), not the display name. The 
airtable-filters
skill covers compound filters, date filters, and operator-by-field-type details.
Search records — use 
search-records
for free-text/fuzzy queries on large tables. Use 
list-records-for-table
with 
--filters
when filtering by exact field values:
sh
airtable-mcp search-records \
  --baseId appEXAMPLEbase001 --table tblEXAMPLEtable01 \
  --query "acme" --fields '["Name","Notes"]' -q
Pass 
--fields ALL_SEARCHABLE_FIELDS
to search across every indexed field. Date, rating, checkbox, and button fields are not searchable.
Update records — complex args are easier via 
--input -
:
sh
echo '{"baseId":"appEXAMPLEbase001","tableId":"tblEXAMPLEtable01","records":[{"id":"recEXAMPLErecord1","fields":{"fldEXAMPLEfield01":"Done"}}]}' \
  | airtable-mcp update-records-for-table --input - -q
Select field values are returned as objects (
{"id":"sel...","name":"Done"}
) but must be written as plain strings (
"Done"
). Record field keys in create/update currently require field IDs (
fldEXAMPLEfield02
) — use 
get-table-schema
to resolve names to IDs before writing. Note that 
fieldIds
, 
sort
, and 
filters
accept both names and IDs.
查找工作区并列出其表格：
sh
airtable-mcp search-bases --searchQuery "Project Tracker" -q
airtable-mcp list-tables-for-base --baseId appEXAMPLEbase001 -q
列出包含指定字段的记录：
sh
airtable-mcp list-records-for-table \
  --baseId appEXAMPLEbase001 --tableId tblEXAMPLEtable01 \
  --fieldIds '["Name","Status"]' --pageSize 10 -q
过滤记录 — 过滤使用结构化JSON，而非公式字符串。将条件包裹在
operands
数组中；若省略顶层
operator
，默认值为
and
：
sh
airtable-mcp list-records-for-table \
  --baseId appEXAMPLEbase001 --tableId tblEXAMPLEtable01 \
  --filters '{"operator":"and","operands":[{"operator":"=","operands":["Status","Done"]}]}' -q
对于单选字段，请通过选项ID（来自
get-table-schema
）进行过滤，而非显示名称。
airtable-filters
技能涵盖复合过滤、日期过滤及按字段类型选择操作符的详细说明。
搜索记录 — 在大型表格中进行自由文本/模糊查询时使用
search-records
。当需要按字段精确值过滤时，请使用
list-records-for-table
并搭配
--filters
参数：
sh
airtable-mcp search-records \
  --baseId appEXAMPLEbase001 --table tblEXAMPLEtable01 \
  --query "acme" --fields '["Name","Notes"]' -q
传递
--fields ALL_SEARCHABLE_FIELDS
可搜索所有已索引字段。日期、评分、复选框和按钮字段不可搜索。
更新记录 — 复杂参数更适合通过
--input -
传递：
sh
echo '{"baseId":"appEXAMPLEbase001","tableId":"tblEXAMPLEtable01","records":[{"id":"recEXAMPLErecord1","fields":{"fldEXAMPLEfield01":"Done"}}]}' \
  | airtable-mcp update-records-for-table --input - -q
单选字段的值会以对象形式返回（
{"id":"sel...","name":"Done"}
），但写入时必须以纯字符串形式传递（
"Done"
）。目前创建/更新记录时的字段键需要使用字段ID（
fldEXAMPLEfield02
）—— 写入前请使用
get-table-schema
将字段名称解析为ID。注意
fieldIds
、
sort
和
filters
参数同时接受字段名称和ID。

Gotchas

常见问题

ProblemCauseFix
Unknown tool: X
Tool name doesn't exist on the server or cache is staleRun 
airtable-mcp tools --refresh
to refresh, then retry
Authentication failed
Token expired, revoked, or wrongRun 
airtable-mcp configure
or check 
AIRTABLE_TOKEN
Access denied
Token missing required scopesAdd scopes at https://airtable.com/create/tokens
Connection timed out
Server unreachable (10s timeout)Check network; CLI falls back to stale cache if available
Boolean flags take no value
--dryRun true
passes 
"true"
as next arg		Use 
--dryRun
alone (booleans are presence-based)
Array/object args failValue isn't valid JSONPass as JSON string: 
--fieldMappings '{"a":"b"}'
Filter rejected at top levelSingle condition passed without 
operands
wrapper		Wrap in 
{"operands":[...]}
(
operator
defaults to 
and
)
Sort key is 
fieldId
not 
field
--sort '[{"field":"Name"}]'
silently ignored		Use 
{"fieldId":"Name","direction":"asc"}
— accepts field IDs or names
Select filter returns no matchesFiltering by display name instead of choice IDRun 
get-table-schema
first to get 
sel...
choice IDs
INVALID_RECORDS
on batch write		Batch limit is 10 records per request (default; varies by account)Split into chunks of ≤10 and check 
<tool> --help
for the current limit
Permission error on 
list-records-for-table
User has interface-only access to the baseUse 
list-records-for-page
/ 
get-record-for-page
instead
Endpoints restrictedCLI only allows HTTPS on 
*.airtable.com
Cannot point at arbitrary servers (security constraint)
问题原因解决方案
Unknown tool: X
工具名称在服务器上不存在，或缓存已过期运行
airtable-mcp tools --refresh
刷新缓存后重试
Authentication failed
令牌已过期、被撤销或不正确运行
airtable-mcp configure
或检查
AIRTABLE_TOKEN
环境变量
Access denied
令牌缺少所需的权限范围在https://airtable.com/create/tokens添加权限范围
Connection timed out
无法连接服务器（超时时间为10秒）检查网络连接；若有可用的过期缓存，CLI会自动回退使用
布尔型参数无法接受值
--dryRun true
会将
"true"
作为下一个参数传递		单独使用
--dryRun
（布尔型参数基于是否存在来判断）
数组/对象参数执行失败值不是有效的JSON以JSON字符串形式传递：
--fieldMappings '{"a":"b"}'
顶层过滤条件被拒绝单个条件未包裹在
operands
中		将条件包裹在
{"operands":[...]}
中（
operator
默认值为
and
）
排序键应为
fieldId
而非
field
--sort '[{"field":"Name"}]'
会被静默忽略		使用
{"fieldId":"Name","direction":"asc"}
—— 同时接受字段ID和名称
单选字段过滤无匹配结果使用显示名称而非选项ID进行过滤先运行
get-table-schema
获取
sel...
格式的选项ID
批量写入时出现
INVALID_RECORDS
错误		每次请求的批量限制为10条记录（默认值；随账户不同而变化）将记录拆分为≤10条的批次，并查看
<tool> --help
获取当前限制
list-records-for-table
出现权限错误		用户仅拥有该工作区的界面访问权限改用
list-records-for-page
/ 
get-record-for-page
工具
端点受限CLI仅允许通过HTTPS访问
*.airtable.com
无法指向任意服务器（安全限制）