airtable-user-mcp

Community add-on to the official Airtable MCP — 72 tools + manage_tools your AI assistant can't get from the public REST API

npm · MCP	MCP Registry	MCP Protocol	VS Code Ext.

Not affiliated with Airtable Inc. This is a community-maintained project.

Active development — Breaking changes may land between minor versions. Pin to a version if you need stability.

TL;DR

npx -y airtable-user-mcp login          # one browser login
claude mcp add airtable --scope user -- npx -y airtable-user-mcp

Done. Your AI assistant can now do things like:

"Create a rollup field on Projects called Total Spend that sums {Amount} from the linked Invoices table, and add a filter to the Active view that hides rows where Total Spend = 0."

The official Airtable MCP can't — its REST API doesn't expose those surfaces. Run both MCPs side-by-side and your AI client sees every tool from each.

Why this is an add-on, not a replacement

The official Airtable MCP is a thin wrapper over the public Web API. That API — by design — never exposed some of the most-requested automation surfaces in Airtable. airtable-user-mcp uses Airtable's internal API (the same one the web UI calls) to close the gap. The two servers cover different surfaces, so the intended setup is both installed at once — your MCP client sees the union of their tool sets.

Coverage map

Backed by Airtable's MCP docs, the Web API reference, and the rollup-field UNSUPPORTED_FIELD_TYPE_FOR_CREATE thread.

Demo

Quick Start

npx airtable-user-mcp

That's it. Your MCP client connects via stdio and gets access to all 73 tools (72 Airtable tools + manage_tools).

When the daemon is running (started automatically by the VS Code extension, or via npx airtable-user-mcp daemon start), subsequent npx airtable-user-mcp invocations transparently proxy their stdio to the shared daemon — so all clients share one Chromium session. To skip the daemon and run in-process: AIRTABLE_NO_DAEMON=1 npx airtable-user-mcp.

Sharing one daemon across clients

A client that attaches to a running daemon runs under that daemon's configuration, not its own.

Only AIRTABLE_NO_DAEMON and AIRTABLE_USER_MCP_HOME are read on the attaching side. Everything else the client was configured with — AIRTABLE_AUTH_MODE, AIRTABLE_HTTP_CLIENT, browser channel, idle-park tuning — belongs to the process that actually executes the tool calls, which is the daemon. Since the VS Code extension now starts a daemon whenever an MCP tool call needs one, a daemon.lock exists on essentially every session, and a standalone client (Claude Desktop, Cursor, Cline, Amp) on the same machine will normally attach to it.

This is deliberate. Airtable's persistent browser profile is single-owner: a second process driving its own Chromium against it crashes (Chrome exit 21, which surfaces confusingly as "session dead"). One shared browser is what prevents that, so refusing the attach would trade a configuration surprise for a crash loop.

What you get instead is a notification. On attach, the client prints one stderr line naming every setting that differs, for example:

[airtable-mcp] attached to the daemon already running at pid 41233 (port 8723); it was started with a
different configuration, and ITS settings apply, not this client's: authMode=browser (you configured byo).
Daemon configDir=/home/you/.airtable-user-mcp. To run under your own settings instead, set
AIRTABLE_NO_DAEMON=1 for this client, or stop the daemon (`npx airtable-user-mcp daemon stop`) and let it
restart from your env.

To check after the fact which settings are actually in force, GET /daemon/health or manage_daemon action=status both report the daemon's effective authMode, httpClient and configDir.

Two ways to opt out: set AIRTABLE_NO_DAEMON=1 for that client (it runs in-process under its own settings — do not do this while another browser-mode daemon is live), or stop the daemon and let it restart from the environment you want.

Run alongside the official Airtable MCP

airtable-user-mcp is designed to add capabilities, not replace anything. The official Airtable MCP handles records over HTTP with PAT/OAuth; this one handles schema, formulas, views, and extensions locally via Airtable's internal API. Register both in your MCP client so your AI assistant sees the union of their tool sets.

Add this entry to your mcpServers block:

{
  "mcpServers": {
    "airtable-user-mcp": {
      "command": "npx",
      "args": ["-y", "airtable-user-mcp"]
    }
  }
}

Then register the official server following Airtable's setup guide. The two servers are independent and share nothing — they just coexist under different names in your MCP client.

Supported Clients

Works with any MCP-compatible client. Tested with:

Claude Desktop	Claude Code	Cursor	Windsurf	Cline	Amp

Advanced GUI

For a visual management experience, install the Airtable Formula VS Code extension. It bundles this MCP server and adds:

• One-click MCP registration for Cursor, Windsurf, Claude Code, Cline, and Amp
• Dashboard with session status, version info, and setup wizard
• Airtable login with credentials in OS keychain and auto-refresh
• Formula editor with syntax highlighting, IntelliSense, and beautify/minify

Claude Quick Start (no VS Code extension)

Five commands take you from zero → a working Airtable MCP in Claude Desktop or Claude Code. Everything below runs from a normal terminal.

Prerequisites

• Node.js 18 or newer — node -v to check. Install from nodejs.org if missing.
• An Airtable account (personal, team, or enterprise — anything you can log into at airtable.com).

1. Check what's already on your machine

npx -y airtable-user-mcp@latest doctor

doctor prints your Node version, platform, config dir, and whether the browser engine is installed. If Patchright: not installed appears, continue to step 2. If it says installed, skip to step 3.

2. Install the browser engine (one-time, ~170 MB)

npx -y airtable-user-mcp install-browser

This downloads Patchright (a stealth Chromium fork used only for the login flow). You only need to run this once per machine. If you already have Chrome, Edge, or Chromium installed and prefer not to download another browser, see Browser Choice below.

3. Log in to Airtable

npx -y airtable-user-mcp login

A browser window opens on airtable.com/login. Sign in like you normally would — password, SSO, 2FA, whatever your account uses. The window closes automatically when login is detected. Your session is stored in ~/.airtable-user-mcp/.chrome-profile/ and reused by every tool call.

Verify the session landed:

npx -y airtable-user-mcp doctor

You should see Session: signed in as usrXXXXXXXXXXXXXX. doctor actually probes Airtable, so it is the command that can tell you whether you are signed in.

status is a quick inventory of what is on disk (Browser profile: present, Daemon: …) and deliberately makes no claim about the session — the files exist whether or not the login completed.

4. Configure your Claude client

{
  "mcpServers": {
    "airtable": {
      "command": "npx",
      "args": ["-y", "airtable-user-mcp"]
    }
  }
}

# Add for all projects on this machine:
claude mcp add airtable --scope user -- npx -y airtable-user-mcp

# OR — add to the current project only (creates .mcp.json, safe to commit):
claude mcp add airtable --scope project -- npx -y airtable-user-mcp

claude mcp list

5. Try it out

Ask your Claude client:

"List all tables in my Airtable base appXXXXXXXXXXXXXX."

It will call list_tables and return the names and IDs.

Troubleshooting

Run npx -y airtable-user-mcp doctor at any time for a full diagnostic.

Browser Choice

If you already have Chrome, Edge, or a system Chromium and want to skip the 170 MB download:

# point the server at an existing Chromium-family browser
export AIRTABLE_BROWSER_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"   # macOS
# or on Windows (PowerShell):
$env:AIRTABLE_BROWSER_PATH = "C:\Program Files\Google\Chrome\Application\chrome.exe"

Useful environment variables

Installation

Via npx (recommended)

Already covered above — the claude mcp add command or the mcpServers JSON entry both use npx -y airtable-user-mcp under the hood.

Via VS Code / Windsurf / Cursor

Install the Airtable Formula extension — it bundles this server and registers it automatically across all your IDEs. Login and status live in a visual dashboard.

Global install

npm install -g airtable-user-mcp
airtable-user-mcp login

Then reference the binary directly in any MCP config:

{ "mcpServers": { "airtable": { "command": "airtable-user-mcp" } } }

From source

{
  "mcpServers": {
    "airtable": {
      "command": "node",
      "args": ["/path/to/airtable-user-mcp/src/index.js"]
    }
  }
}

All CLI commands

npx airtable-user-mcp                  Start MCP server (stdio)   ← what your Claude client runs
npx airtable-user-mcp login            Log in to Airtable via browser
npx airtable-user-mcp logout           Clear saved session
npx airtable-user-mcp status           Show what's on disk (makes no session claim)
npx airtable-user-mcp doctor           Run diagnostics + probe whether you're signed in
npx airtable-user-mcp install-browser  Download Chromium (~170 MB)
npx airtable-user-mcp --version        Print version
npx airtable-user-mcp --help           Show this help
npx airtable-user-mcp daemon start     Start the shared background daemon
npx airtable-user-mcp daemon stop      Stop the running daemon
npx airtable-user-mcp daemon status    Show daemon status and port (JSON)

Tools (72 + manage_tools)

72 tools are gated by the active tool profile (read-only / safe-write / full / custom) and grouped by category below. manage_tools — list profiles, switch the active profile, toggle individual tools/categories — is a meta-tool always available regardless of profile, so a connected client's tools/list returns 73 tools total under the default full profile.

Schema Read (11)

Record Read (1)

Reads resolved record data via Airtable's internal readQueries endpoint — bypasses the REST API filterByFormula limitation that silently fails on lookup and rollup fields.

Why query_records instead of the Official MCP's record search

// ❌ REST API filterByFormula — silently fails for lookup fields
//    FIND() operates on the raw cell value, not the resolved display string
filterByFormula: "FIND('John Smith', {Name Lookup})"   // returns 0 results

// ✅ query_records.search — works on all field types
{ "search": "john smith", "limit": 500 }   // matches any field containing "john smith"

Record Write (4)

Record Destructive (1)

Table Management (3)

Field Management (9)

View Configuration (20)

Sidebar Sections (4)

Record Templates (8)

Saved row scaffolds Airtable surfaces under "+ Add record" and the row-create extension. Cell values can be static, linked rows, or references to other templates.

Form Metadata (2 — legacy form views only)

Extension Management (7)

Base Sync (1)

Typical diff → curate → apply workflow:

1. mode=diff — compare bases, review the digest. Verdict converged means no drift; identical means nothing to do.
2. mode=plan — generate the full changeset. Edit apply:false on any changeId entries you want to skip, or collect their IDs. When direction=to-source, the plan is persisted under the swapped base pair, so applying it requires calling mode=apply with sourceAppId and destAppId swapped accordingly.
3. mode=apply skip=[...] — execute the plan minus excluded changes.

Daemon Control (1)

Administers this server's own process — no Airtable API surface. full profile only, and the daemon category defaults to off for existing custom profiles.

Usage Examples

Inspect a base schema

Tool: list_tables
Args: { "appId": "appXXXXXXXXXXXXXX" }

Create and validate a formula

Tool: validate_formula
Args: { "appId": "appXXX", "tableId": "tblXXX", "formulaText": "IF({Price}>0,{Price}*{Qty},0)" }

Tool: create_formula_field
Args: { "appId": "appXXX", "tableId": "tblXXX", "name": "Total", "formulaText": "IF({Price}>0,{Price}*{Qty},0)" }

Search records (including lookup fields)

Tool: query_records
Args: {
  "appId": "appXXXXXXXXXXXXXX",
  "tableId": "tblXXX",
  "viewId": "viwXXX",
  "search": "john smith",
  "limit": 500
}

Returns every record in the view where any field value contains "john smith" — including fields whose value comes from a lookup, rollup, or formula. The Official Airtable MCP's filterByFormula with FIND() or SEARCH() silently fails on lookup fields; query_records does not.

Configure view filters

Tool: update_view_filters
Args: {
  "appId": "appXXX",
  "viewId": "viwXXX",
  "filters": {
    "filterSet": [
      { "columnId": "fldXXX", "operator": "isNotEmpty" }
    ],
    "conjunction": "and"
  }
}

Safety

• Destructive operations (delete_table, delete_field, delete_fields, delete_view, remove_extension) include built-in safety guards
• delete_table, delete_field, and each entry in delete_fields all require an expectedName that must match the current field name exactly — prevents accidentally deleting the wrong object after a rename
• delete_field checks for downstream dependencies and returns a compact summary (viewGroupings, viewSorts, viewFilters, fields) before committing; set force: true to delete anyway
• delete_fields is the preferred tool for bulk deletion (dozens to hundreds of fields). It uses Airtable's native batch endpoint, so N fields from the same table cost 1–2 API calls instead of N×3. Set force: true to delete even fields with downstream dependencies.
• Formula validation is available and recommended before creating/updating formulas
• All tools accept debug: true for raw response inspection

ID Format Reference

Transport Modes

airtable-user-mcp supports three transport modes. The default behaviour is automatic — MCP clients do not need to change their configuration when the daemon is present.

The daemon stores its port and bearer token in ~/.airtable-user-mcp/daemon.lock.

Clients that cannot send an Authorization header — e.g. claude.ai custom connectors, which only support OAuth or no-auth — can pass the token in the URL instead: https://<tunnel-host>/mcp?token={token}. The URL then IS the secret: share it only with the client, and rotate via manage_daemon action=token_rotate if it leaks.

Protocol

Find Us

Related

• Official Airtable MCP — Airtable's first-party remote server for records over HTTP; this add-on runs alongside it
• Airtable Formula VS Code Extension — Dashboard, formula editor, MCP installer, and AI skills
• Model Context Protocol — The open standard for AI tool integration

Support This Project

This project is built and maintained with the help of AI coding tools. If you find it useful and want to support continued development (new tools, updates, bug fixes), you can contribute by gifting Claude Code credits — the primary tool used to build this project.

Interested? Open an issue or reach out to discuss feature requests and sponsorship.

License

MIT