Skip to content
Skills Library
Data & analytics · Tool integration

airtable-cli

/airtable-cli

Lists bases, reads and writes records, manages tables and fields, filters and searches data in Airtable via the `airtable-mcp` CLI. Use when the task involves Airtable data or the user mentions airtable-mcp, bases, tables, records, or fields.

Repository
skills ↗
Licence
MIT
Last repository change
21.07.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 21.07.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Lists bases, reads and writes records, manages tables and fields, filters and searches data in Airtable via the `airtable-mcp` CLI. Use when the task involves Airtable data or the user mentions airtable-mcp, bases, tables, records, or fields.

Original author description

Lists bases, reads and writes records, manages tables and fields, filters and searches data in Airtable via the `airtable-mcp` CLI. Use when the task involves Airtable data or the user mentions airtable-mcp, bases, tables, records, or fields.

How it works

  1. Self-discovery
  2. Install
  3. Auth
  4. Quick reference
  5. Workflow
  6. Output & automation
  7. Common tasks
  8. Gotchas
Original SKILL.md headings · 141 lines, 951 words
SKILL.md preview
---
name: airtable-cli
description: Lists bases, reads and writes records, manages tables and fields, filters and searches data in Airtable via the `airtable-mcp` CLI. Use when the task involves Airtable data or the user mentions airtable-mcp, bases, tables, records, or fields.
license: MIT
metadata:
    version: '1.0.0'
    author: airtable
---

# 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.

## Install

```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.

## Quick reference

| Task                   | Command                                                 |
| ---------------------- | ------------------------------------------------------- |
| 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.

## 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`

## 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).

## 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.

## Gotchas

| Problem                                      | Cause                                                              | Fix                                                                      |
| -------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------ |
| `Unknown tool: X`                            | Tool name doesn't exist on the server or cache is stale            | Run `airtable-mcp tools --refresh` to refresh, then retry                |
| `Authentication failed`                      | Token expired, revoked, or wrong                                   | Run `airtable-mcp configure` or check `AIRTABLE_TOKEN`                   |
| `Access denied`                              | Token missing required scopes                                      | Add 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 fail                       | Value isn't valid JSON                                             | Pass as JSON string: `--fieldMappings '{"a":"b"}'`                       |
| Filter rejected at top level                 | Single 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 matches             | Filtering by display name instead of choice ID                     | Run `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 base                         | Use `list-records-for-page` / `get-record-for-page` instead              |
| Endpoints restricted                         | CLI only allows HTTPS on `*.airtable.com`                          | Cannot point at arbitrary servers (security constraint)                  |

Versions

The database has no other skills named airtable-cli.

Database snapshot: 13.11.2026 · package version 7cc22300ad48 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 85airtable-overview
    Explains what Airtable is and how data is structured — bases, tables, fields, records, views, automations, and interfaces. Use when you need context about the Airtable data model.
  • 100airtable-filters
    Use this skill when the user wants to find, filter, or narrow down Airtable records by field values, even when they don't explicitly say "filter.
  • 100airtable
    Airtable is a hosted spreadsheet-database; its Web API reads and writes records, table schema, attachments and webhooks over REST. Use when tasks involve reading or writing Airtable data, importing or upserting rows from a CSV or another system, syncing external sources with…
  • 100airtable-filters
    Builds Airtable filters parameters for the MCP tools that list or display records — field-type-aware comparison operators, choice and collaborator IDs, date ranges, and nested AND/OR logic. Use when the user wants to find, filter, narrow down, or search Airtable records by field…
  • 100operate-airtable
    Use when scripting Airtable — scoped PATs, rate limits and 10-record batches, field IDs over names, expiring webhooks, per-environment bases with a schema diff, and tables owned by other systems left read-only.
  • 100airtable-webhooks
    Receive and verify Airtable webhooks. Use when setting up Airtable webhook handlers, debugging X-Airtable-Content-MAC signature verification, handling the thin-ping notification, or fetching base changes (tableData, tableFields, tableMetadata add/remove/update) from the webhook payloads API.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.