Airtable

View saved version →

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

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

**List records with specific fields:**

```sh
airtable-mcp list-records-for-table \
  --baseId appK9MtBqFw3o5jGN --tableId tblL4GpTfEz8byRsW \
  --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 appK9MtBqFw3o5jGN --tableId tblL4GpTfEz8byRsW \
  --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 appK9MtBqFw3o5jGN --table tblL4GpTfEz8byRsW \
  --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":"appK9MtBqFw3o5jGN","tableId":"tblL4GpTfEz8byRsW","records":[{"id":"recVnR3xPq8sD2yLk","fields":{"fld8WsrpLHHevsnW8":"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 (`fldXXX`) — 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)                  |

Referenced files: 1

View saved version →

---
name: airtable-filters
description: 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."
license: MIT
metadata:
  version: '1.0.0'
  author: airtable
---

# Airtable MCP Filters

MCP tools that list or display records from tables or interface pages accept an optional `filters` parameter, using the same schema.

When querying records from an interface page, these filters are combined with the page's built-in filters using AND.

## Schema shape

When no top-level `operator` is specified, conditions are combined with AND. The first element in a condition's `operands` array is always a **field ID** — look up the table's schema to find field IDs before filtering.

## Field type categories

-   **Text-like**: singleLineText, multilineText, email, url, phoneNumber, richText, barcode
-   **Numeric**: number, percent, currency, rating, duration, autoNumber, count
-   **Date**: date, dateTime, createdTime, lastModifiedTime
-   **Single select**: singleSelect
-   **Multiple selects**: multipleSelects
-   **Single collaborator**: singleCollaborator
-   **Multiple collaborators**: multipleCollaborators
-   **Linked records**: multipleRecordLinks
-   **Attachment**: multipleAttachments
-   **Checkbox**: checkbox

Computed fields (formula, rollup, lookup) support whichever operators match their result type.

## Comparison operators

| Operator                | Second operand                     | Field categories                                                                                                                   |
| ----------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `=`                     | string, number, boolean, choice ID | text-like, numeric, date, checkbox, single select, multiple selects, single collaborator, multiple collaborators, linked records   |
| `!=`                    | string, number, choice ID          | text-like, numeric, date, single select, single collaborator                                                                       |
| `<`, `>`, `<=`, `>=`    | number or date value object        | numeric, date                                                                                                                      |
| `contains`              | string                             | text-like, linked records                                                                                                          |
| `doesNotContain`        | string                             | text-like, linked records                                                                                                          |
| `doesNotContain`        | array of IDs                       | multiple selects, multiple collaborators                                                                                           |
| `isEmpty`, `isNotEmpty` | _(none)_                           | text-like, numeric, date, single select, multiple selects, single collaborator, multiple collaborators, linked records, attachment |
| `hasAnyOf`, `hasAllOf`  | array of IDs                       | multiple selects, multiple collaborators, linked records                                                                           |
| `isAnyOf`               | array of IDs                       | single select, single collaborator                                                                                                 |
| `isNoneOf`              | array of IDs                       | single select, single collaborator, linked records                                                                                 |
| `isWithin`              | date range object                  | date                                                                                                                               |
| `filename`, `fileType`  | string or `"image"`/`"text"`       | attachment                                                                                                                         |

When matching a field against multiple values, prefer dedicated operators (`isAnyOf`, `isNoneOf`, `hasAnyOf`, `hasAllOf`) over combining multiple `=` conditions with `or`/`and`, when those operators are available for the field type.

## Field-type rules

### Select fields

For select fields, operand values must be **choice IDs** (e.g., `"selABCDEFGHIJKLM"`), not display names. Look up the table's schema to find choice IDs before filtering.

### Collaborator fields

When filtering by a collaborator group ID, use `operatorOptions` to match individual members of the group instead of the literal group ID. See the tool's `operatorOptions` parameter for details.

Example operand: `{"operator": "hasAnyOf", "operands": ["fldCRi9oz2vRLcIWr", "ugpDUVUnftA7H9bG8"], "operatorOptions": {"matchGroupsByMembership": true}}`

### Attachment fields

Use `fileType` to filter attachments by type (e.g., `"image"`, `"text"`) rather than `isNotEmpty` when the user specifies a file type.

### Date fields

Date comparisons (`=`, `!=`, `<`, `>`, `<=`, `>=`) use a date value object instead of a raw date string, and `isWithin` uses a date range object. The tool schema defines the available modes for each. Always include `timeZone`.

## Composing conditions

A filter's top-level operands array can contain two or more conditions, which are combined with the top-level operator (AND by default). For simple multi-condition filters, this flat structure is sufficient.

When the logic requires mixing AND and OR, nest a filter object as one of the operands. Each nested filter has its own operator and operands.

**OR inside AND** — useful when one condition is fixed and another allows multiple alternatives:

> "Scripted videos that are either in Writing or Pre-Production"
> → Bucket = Scripted AND (Status = Writing OR Status = Pre-Production)

**AND inside OR** — useful when you want records matching either a simple condition or a combination:

> "Approved videos, or videos assigned to Bailey that are in Cut 2"
> → Status = Approved OR (Editor = Bailey AND Status = Cut 2 Ready)

When combining many conditions on different fields, prefer a flat AND rather than unnecessary nesting. Only nest when the logic genuinely requires mixed AND/OR at different levels.

Prefer composing all conditions into a single `filters` object rather than splitting them across multiple calls. A single call with a composed filter is more efficient and returns the correct result set directly.

## Examples

Filter where a text field equals "orange" OR a number field is greater than 5:

```json
{
    "operator": "or",
    "operands": [
        {"operator": "=", "operands": ["fld8WsrpLHHevsnW8", "orange"]},
        {"operator": ">", "operands": ["fldulcCPDVz87Bmnw", 5]}
    ]
}
```

Filter for records where a date field is within the past week:

```json
{
    "operands": [
        {
            "operator": "isWithin",
            "operands": ["fldABC12345678x", {"mode": "pastWeek", "timeZone": "America/New_York"}]
        }
    ]
}
```

Referenced files: 1

View saved version →

---
name: airtable-overview
description: 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.
license: MIT
metadata:
  version: '1.0.0'
  author: airtable
---

# Airtable Overview

Airtable is a no-code platform where teams build custom applications and AI-powered workflows from structured data. Users organize their data into bases, define tables with typed fields, set up automations to act on changes, and create interfaces that give different audiences tailored views of the same data.

## Data model

### Bases

A base is an Airtable database. It is the top-level container for all related data. A base contains one or more tables.

### Tables

A table is a collection of structured data within a base, similar to a sheet in a spreadsheet or a table in a relational database. Each table has a defined set of fields and contains records.

### Fields

A field defines a named, typed property on every record in a table.

### Records

A record is a single entry in a table. Each record has a unique ID and stores a cell value for each field defined on that table.

### Views

A view is a saved configuration for how to display records in a table. Views can filter, sort, group, and hide fields without changing the underlying data. Multiple views can exist on the same table, each showing the data differently.

## Automations

An automation is a workflow that runs in response to a defined trigger (e.g. a record entering a view) and executes one or more actions (e.g. sending an email or updating a record).

## Interfaces

Interfaces are custom app-like pages built on top of base data. They provide tailored, user-friendly ways to view and interact with records without exposing the full base structure or all of its data. A base can have multiple interfaces, each designed for a specific workflow or audience.

Some users can only access a base through its interfaces and cannot read or modify the underlying tables directly.

Referenced files: 1