airtable-agent-cli

A full-coverage CLI and MCP server for the Airtable API — built for AI agents and humans alike.

21 commands across bases, tables, fields, records, views, and webhooks
MCP server — plug directly into Claude, Cursor, VS Code, or any MCP-compatible AI client
Dual interface — every command works as both a CLI tool and an MCP tool from the same codebase
Agent-native — rich descriptions, upsert, formula filtering, batch ops, and pagination built in

Installation

npm install -g airtable-agent-cli

Or use without installing:

npx airtable-agent-cli --help

Authentication

Get a Personal Access Token at airtable.com/create/tokens.

Required scopes:

schema.bases:read — list bases, tables, fields
schema.bases:write — create/update tables and fields
data.records:read — read records
data.records:write — create, update, delete, upsert records
webhook:manage — manage webhooks

Store credentials

airtable login
# or non-interactively:
airtable login --token pat_XXXXXXXXXX

Environment variable

export AIRTABLE_TOKEN=pat_XXXXXXXXXX

Per-command flag

airtable records list --base appXXX --table tblXXX --token pat_XXXXXXXXXX

Commands

Bases

airtable bases list                            # List all accessible bases
airtable bases schema --base appXXX            # Full schema: tables + fields + views

Tables

airtable tables list --base appXXX
airtable tables create --base appXXX --name "Contacts" \
  --fields '[{"name":"Name","type":"singleLineText"}]'
airtable tables update --base appXXX --table tblXXX --name "New Name"

Fields

airtable fields list --base appXXX --table tblXXX
airtable fields create --base appXXX --table tblXXX --name "Email" --type email
airtable fields create --base appXXX --table tblXXX --name "Status" --type singleSelect \
  --options '{"choices":[{"name":"Active"},{"name":"Inactive"}]}'
airtable fields update --base appXXX --table tblXXX --field fldXXX --name "New Name"

Records

# List with filtering, sorting, pagination
airtable records list --base appXXX --table tblXXX
airtable records list --base appXXX --table tblXXX --formula "AND({Status}='Active')"
airtable records list --base appXXX --table tblXXX --select "Name,Email,Status"
airtable records list --base appXXX --table tblXXX --sort "Name:asc,CreatedTime:desc"
airtable records list --base appXXX --table tblXXX --view "Grid view" --max-records 50
airtable records list --base appXXX --table tblXXX --offset "itrXXXXXXXXXXXXXX"

# Get single record
airtable records get --base appXXX --table tblXXX --record recXXX

# Create (single or batch, max 10)
airtable records create --base appXXX --table tblXXX \
  --fields '{"Name":"Alice","Email":"[email protected]"}'
airtable records create --base appXXX --table tblXXX \
  --records '[{"fields":{"Name":"Alice"}},{"fields":{"Name":"Bob"}}]'

# Partial update / PATCH (only provided fields change)
airtable records update --base appXXX --table tblXXX \
  --record recXXX --fields '{"Status":"Done"}'
airtable records update --base appXXX --table tblXXX \
  --records '[{"id":"recAAA","fields":{"Status":"Done"}},{"id":"recBBB","fields":{"Status":"Active"}}]'

# Full replace / PUT (unincluded fields are cleared)
airtable records replace --base appXXX --table tblXXX \
  --record recXXX --fields '{"Name":"Alice","Status":"Active"}'

# Delete (single or comma-separated batch, max 10)
airtable records delete --base appXXX --table tblXXX --record recXXX
airtable records delete --base appXXX --table tblXXX --records "recAAA,recBBB,recCCC"

# Upsert — update if exists, create if not
airtable records upsert --base appXXX --table tblXXX \
  --merge-on "Email" \
  --fields '{"Name":"Alice","Email":"[email protected]","Status":"Active"}'
airtable records upsert --base appXXX --table tblXXX \
  --merge-on "Email,ExternalId" \
  --records '[{"fields":{"Email":"[email protected]","Name":"Alice"}},{"fields":{"Email":"[email protected]","Name":"Bob"}}]'

Views

airtable views list --base appXXX             # Enterprise only

Webhooks

airtable webhooks list --base appXXX
airtable webhooks create --base appXXX \
  --notify-url "https://example.com/hook" \
  --data-types "tableData"
airtable webhooks create --base appXXX \
  --notify-url "https://example.com/hook" \
  --data-types "tableData,tableFields,tableMetadata" \
  --record-scope tblXXX
airtable webhooks refresh --base appXXX --webhook achXXX
airtable webhooks payloads --base appXXX --webhook achXXX
airtable webhooks delete --base appXXX --webhook achXXX

Output Formats

# Compact JSON (default — pipe-friendly)
airtable records list --base appXXX --table tblXXX

# Pretty-printed JSON
airtable records list --base appXXX --table tblXXX --pretty

# Select specific output fields
airtable records list --base appXXX --table tblXXX --fields id,fields

# Quiet — exit codes only (0 = success, 1 = error)
airtable records delete --base appXXX --table tblXXX --record recXXX --quiet

MCP Server (AI Agent Integration)

Run as an MCP server so AI assistants can call Airtable directly:

airtable mcp

Claude Desktop / Cursor / VS Code

Add to your MCP config (~/.claude/config.json, .cursor/mcp.json, etc.):

{
  "mcpServers": {
    "airtable": {
      "command": "npx",
      "args": ["airtable-agent-cli", "mcp"],
      "env": {
        "AIRTABLE_TOKEN": "pat_XXXXXXXXXX"
      }
    }
  }
}

If installed globally:

{
  "mcpServers": {
    "airtable": {
      "command": "airtable",
      "args": ["mcp"],
      "env": {
        "AIRTABLE_TOKEN": "pat_XXXXXXXXXX"
      }
    }
  }
}

Available MCP Tools

All 21 CLI commands are exposed as MCP tools with the same names:

Tool	Description
`bases_list`	List all accessible bases
`bases_schema`	Get full base schema (tables, fields, views)
`tables_list`	List tables in a base
`tables_create`	Create a new table
`tables_update`	Update table name/description
`fields_list`	List fields in a table
`fields_create`	Create a new field
`fields_update`	Update field name/description
`records_list`	List records with filtering, sorting, pagination
`records_get`	Get a single record by ID
`records_create`	Create one or more records
`records_update`	Partially update records (PATCH)
`records_replace`	Fully replace records (PUT)
`records_delete`	Delete one or more records
`records_upsert`	Upsert records by merge fields
`views_list`	List views in a base
`webhooks_list`	List webhooks
`webhooks_create`	Create a webhook
`webhooks_delete`	Delete a webhook
`webhooks_refresh`	Refresh webhook expiration
`webhooks_payloads`	Fetch webhook payloads

Scripting & Piping

# Get all active contacts
airtable records list --base appXXX --table tblXXX \
  --formula "{Status}='Active'" | jq '.records[].fields'

# Export record IDs
airtable records list --base appXXX --table tblXXX \
  --fields id | jq -r '.[].id'

# Pipe bases list into jq
airtable bases list | jq '.bases[] | {id, name}'

Architecture

This tool follows a dual CLI/MCP pattern:

A single CommandDefinition[] array powers both the Commander.js CLI and the MCP server
Zod schemas are the source of truth for validation, help text, and MCP input schemas
Every command works identically whether called from the terminal or by an AI agent

CommandDefinition {
  name        →  MCP tool name ("records_list")
  group       →  CLI group ("records")
  subcommand  →  CLI subcommand ("list")
  inputSchema →  Zod schema → CLI validation + MCP input schema
  handler     →  Async function called by both CLI and MCP
}

License

MIT

bcharleson/airtable-agent-cli

README