·

Airtable MCP With Claude Code CLI and VS Code

Set up Airtable MCP in Claude Code CLI and VS Code so your AI agent can read and update bases and records right from your editor.

Claude Code is the strongest fit for Airtable MCP among the four agents in this course, mostly because its permission model (allow/deny per tool call, project-level .mcp.json) maps cleanly onto the risk profile of a records database — you want reads unrestricted and writes gated. This topic walks through the actual setup in both the CLI and the VS Code extension, then gets into query and write patterns you'll use daily on a requirements-tracking base.

Installing and Connecting Airtable MCP to Claude Code

Add the server at the project level so the config lives in .mcp.json next to your repo rather than polluting your global Claude Code settings:

claude mcp add airtable \
  --env AIRTABLE_API_KEY=patAbC123dEf456.gh789ij012kl345mn678op901qr234st567uv890wx123yz456ab789cd012 \
  -- npx -y airtable-mcp-server

This writes to .mcp.json in your project root:

{
  "mcpServers": {
    "airtable": {
      "command": "npx",
      "args": ["-y", "airtable-mcp-server"],
      "env": {
        "AIRTABLE_API_KEY": "patAbC123dEf456.gh789ij012kl345mn678op901qr234st567uv890wx123yz456ab789cd012"
      }
    }
  }
}

Don't commit that literal token. Swap it for a reference and keep the real value in .env:

{
  "mcpServers": {
    "airtable": {
      "command": "npx",
      "args": ["-y", "airtable-mcp-server"],
      "env": {
        "AIRTABLE_API_KEY": "${AIRTABLE_API_KEY}"
      }
    }
  }
}

Verify the connection landed correctly:

claude mcp list

If it shows "✗ Failed to connect," the two usual causes are a malformed PAT (missing the . separator between the token ID and secret) or the PAT not being attached to any base — Airtable returns an empty base list rather than an auth error in that case, which the MCP server sometimes surfaces as a generic connection failure.

For the VS Code extension, Airtable MCP is configured the same way through the Claude Code panel's MCP settings UI, or by pointing it at the same project-level .mcp.json — VS Code respects the project config if you open the folder as the workspace root. Restart the extension host (Cmd/Ctrl+Shift+P → "Developer: Reload Window") after adding a new server; it doesn't hot-reload .mcp.json changes mid-session.

Once connected, sanity-check tool discovery inside a session:

/mcp

This lists connected servers and their exposed tools — confirm list_bases, list_records, create_record, update_records all appear before doing real work.

Tips
- Use claude mcp add --scope project (the default when a .mcp.json doesn't already exist elsewhere) so teammates get the same server config when they clone the repo — they still supply their own PAT via .env.
- Run /mcp at the start of every new session on an unfamiliar base — server versions drift and tool names occasionally change between releases.
- If VS Code shows the server as connected but tool calls hang, check you're not double-running npx processes from a previous session; kill stray Node processes before retrying.

Querying Bases and Filtering Records from the Terminal

Once connected, the natural workflow is conversational but you get much better results by giving Claude Code the actual field names and filter logic up front rather than a vague ask.

A vague prompt:

Show me the open high-priority requirements

produces an agent that has to guess field names (Priority vs Priority Level, Open vs Status != Done). A grounded prompt, after you've had it run describe_table once earlier in the session:

Query the "Requirements" table, filter where {Status} != "Done" AND {Priority} = "P1",
sort by {Created} descending, return only Title, Status, Priority, Owner, and Created.

The agent translates this into a list_records call using Airtable's formula language directly:

filterByFormula: AND({Status} != "Done", {Priority} = "P1")
sort: [{"field": "Created", "direction": "desc"}]
fields: ["Title", "Status", "Priority", "Owner", "Created"]

Some useful filterByFormula patterns worth memorizing so you can sanity-check what the agent generates:

IS_AFTER({Last Modified}, DATEADD(TODAY(), -7, 'days'))

{Owner} = ""

OR({Status} = "Backlog", {Status} = "Blocked")

FIND("csv export", LOWER({Description})) > 0

For anything returning more than 100 records, remind the agent that Airtable paginates with an offset token — a single list_records call caps at 100 records per page by default. A well-built MCP server handles pagination internally when you ask for "all matching records," but verify: ask it explicitly, "confirm you paginated through all pages, not just the first 100," especially on a base with 500+ requirement records where silently truncated results look plausible.

Tips
- Ask Claude Code to echo back the exact filterByFormula string it's about to run before executing, especially for anything you'll reuse — paste it into a saved Airtable view afterward so non-technical teammates get the same filter without needing the agent.
- Give explicit field names, not descriptions — "the priority field" is ambiguous if your base has both Priority and Customer Priority; describe_table output resolves this once per session.
- Watch for truncated result sets on large tables; explicitly confirm pagination rather than trusting a suspiciously round 100-record result.

Creating and Updating Requirement Records from Code Changes

The workflow that pays for itself fastest: closing the loop between a merged PR and the requirement's status in Airtable. Instead of a human remembering to flip the status, have Claude Code do it as part of your merge routine.

A concrete prompt after a PR merges:

The PR "Add CSV export for feature matrix (REQ-482)" just merged into main.
Find the Airtable record in the Requirements table with Requirement ID REQ-482,
set Status to "Shipped", set Shipped Date to today, and append a note to
AI Notes: "Shipped via PR #214, merged 2026-08-21."
Show me the record before and after the change.

This produces two tool calls: a list_records lookup and an update_records write. The actual payload shape for the write:

{
  "records": [
    {
      "id": "recXYZ123abc456de",
      "fields": {
        "Status": "Shipped",
        "Shipped Date": "2026-08-21",
        "AI Notes": "Shipped via PR #214, merged 2026-08-21."
      }
    }
  ]
}

For creating a fresh requirement from a GitHub issue or a design doc excerpt:

Create a new record in Requirements from this issue text: [paste issue body].
Set Title from the issue title, Description from the body, Priority to P2 unless
the text explicitly says urgent/blocking (then P1), Status to "Backlog",
and link Epic to the existing "Q3 Reporting" epic record.

Claude Code needs to resolve "Q3 Reporting" to a record ID first — a linked-record field write always requires the ID array, never the display name:

{
  "fields": {
    "Title": "Add CSV export for feature matrix",
    "Description": "Users need to export the current feature/plan matrix as CSV...",
    "Priority": "P2",
    "Status": "Backlog",
    "Epic": ["recA1b2C3d4E5f6G7"]
  }
}

If the agent skips the resolve-then-link step and just passes "Epic": ["Q3 Reporting"], Airtable's API returns a 422 — link fields never accept display strings, and this is one of the most common failure modes when developers write ad hoc prompts without having previously run describe_table to reveal that Epic is a link field rather than a text field.

Tips
- Wire the status-sync prompt into a git hook or a Claude Code slash command triggered post-merge rather than remembering to type it manually every time — consistency matters more than cleverness here.
- Always have the agent show a before/after diff on single-record updates; it costs one extra read call and catches wrong-record mistakes (duplicate titles are common in requirement trackers) before they ship.
- When creating records that reference existing entities (epics, components, owners), explicitly instruct "resolve to record ID first" — don't assume the agent remembers linked fields need IDs from a previous session's schema dump.

Prompting Patterns for Safe Bulk Record Operations

Bulk operations are where Airtable MCP earns its keep and also where it can do the most damage fastest. A single loose prompt like "close out all the requirements older than 90 days" against a 2,000-record table can silently touch hundreds of records you didn't mean to touch — stale filter logic, an off-by-one date comparison, or a status value that triggers a downstream Airtable automation you forgot existed.

The safe pattern is always: preview, count, confirm, then execute.

Step 1: Find all records in Requirements where {Status} = "Backlog" AND
{Created} is before 2026-05-01. Show me the count and list the first 10 titles.
Do NOT modify anything yet.

Step 2: [after reviewing] Now update all matching records: set Status to "Stale",
add "Auto-archived by AI review, 2026-08-21" to AI Notes. Confirm the count
matches what you showed me in step 1 before writing.

This two-step pattern costs one extra round trip but catches the two failure modes that actually happen in practice: a filter that's broader than intended, and record-count drift between the preview and the execution (someone else edited the base in between).

For genuinely large bulk jobs — say, backfilling a Component field across 800 records based on keyword matching in Description — batch explicitly rather than letting the agent decide chunk size:

Process the 800 unmatched records in batches of 10 (Airtable's write limit per call).
After each batch, wait for rate limit safety, then continue.
Report progress every 100 records processed.

A batched update_records call, 10 records at a time:

{
  "records": [
    { "id": "rec001", "fields": { "Component": "Billing" } },
    { "id": "rec002", "fields": { "Component": "Auth" } },
    { "id": "rec003", "fields": { "Component": "Reporting" } }
  ]
}

At 5 req/sec per base and 10 records per request, the theoretical ceiling is 50 records/sec — but in practice, budget for roughly half that once you account for the interleaved read calls needed to resolve linked-record IDs and periodic 429 backoffs. An 800-record backfill realistically takes 2-4 minutes end to end, not the few seconds naive math suggests.

Dry-run field before a bulk write is worth adding permanently to any table an agent touches regularly:

Add a checkbox field "AI Reviewed" to Requirements. Before any bulk status change,
first set AI Reviewed = true on the target set and let a human spot-check 10%
of flagged records before the actual status write proceeds.

Tips
- Never let a single prompt both define the filter and execute the write in the same breath for anything touching more than ~20 records — force the preview-then-confirm split every time.
- Ask for progress reporting on any batch over 50 records — silent long-running tool calls make it hard to tell a slow rate-limited job from a hung one.
- Keep an AI Reviewed or Last AI Action field on high-traffic tables; it turns "did the bulk job actually run correctly" from a guess into a query.

Tips

Tips
- Keep Airtable MCP scoped to project-level .mcp.json, not global config — a requirements base for Project A has no business being reachable from an unrelated Project B session.
- Build a short library of your team's actual filterByFormula strings as a markdown reference file in the repo (docs/airtable-filters.md) and point Claude Code at it — it dramatically reduces malformed formula guesses on complex AND/OR nesting.
- Review the VS Code extension's MCP call log (visible in the Claude Code output panel) after your first few bulk sessions — it's the fastest way to catch a filter that matched more records than you expected before it becomes a habit.

Next Airtable MCP With OpenCode