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）が必要です。設定方法は 2 つあります。

環境変数（スクリプト／エージェントでの使用に推奨）：

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 は使用方法のエラー（フラグまたは入力が不正な場合）です。

よくあるタスク

ベースを検索して、テーブルを一覧表示する：

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

選択フィールドでは、表示名ではなく、get-table-schema で取得した選択肢 ID でフィルタリングします。複合フィルター、日付フィルター、フィールド型ごとの演算子の詳細については、airtable-filters スキルを参照してください。

レコードを検索する — 大きなテーブルでフリーテキスト検索やあいまい検索を行うには、search-records を使用します。フィールドの完全一致でフィルタリングするには、--filters を指定して list-records-for-table を使用します。

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

選択フィールドの値はオブジェクト（{"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	サーバーに到達できない（タイムアウトは 10 秒）	ネットワークを確認する。利用可能な場合、CLI は古いキャッシュにフォールバックする
ブール値フラグに値を指定すると失敗する	--dryRun true は次の引数として "true" を渡す	--dryRun のみを使用する（ブール値は指定の有無で判定されます）
配列／オブジェクト引数が失敗する	値が有効な JSON ではない	JSON 文字列として渡す：--fieldMappings '{"a":"b"}'
フィルターが最上位で拒否される	単一条件を operands で囲まずに渡している	{"operands":[...]} で囲む（operator はデフォルトで and になります）
並べ替えキーが field ではなく fieldId	--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 は *.airtable.com の HTTPS のみを許可する	任意のサーバーを指定することはできません（セキュリティ上の制約）