Airtable MCP Server

A remote Model Context Protocol server that exposes the full Airtable Web API to Claude — including document upload and download, which the official Airtable connector does not support.

It runs on Cloudflare Workers, and every user signs in with their own Airtable account via OAuth 2.1 (PKCE-S256). One URL, their own login, done — nobody needs access to your Cloudflare account.

Works as a claude.ai custom connector, in Claude Desktop, and in Claude Code.

It stores nothing

This server is an execution proxy, not a database. It runs tasks and keeps no record of them.

• No storage bindings at all — no KV, no R2, no Durable Objects, no database. Check wrangler.jsonc: there is nothing to store into.

• No credentials at rest. There is no server-side session or grant table. Every token this server issues is a sealed blob (AES-GCM) that the client holds; it carries the user's Airtable credentials inside itself. A request arrives carrying its own authorization, we decrypt it in memory, call Airtable, and discard it.

• No user data. Records stream straight through to the Airtable API. Nothing is cached or logged.

• No documents. Uploaded bytes are passed directly to Airtable's upload endpoint and dropped; downloads return Airtable's own temporary URL.

• No session state. Each HTTP request builds an MCP server instance, answers one message, and throws it away.

The only persistent value is TOKEN_SEALING_KEY — a server secret, not user data. Rotating it invalidates every issued token at once.

Consequence to be aware of: because there are no grant records, there is no server-side "revoke this user" button. Revocation lives where it belongs — a user removes the integration in their own Airtable account settings — and rotating the sealing key logs everyone out.

Related MCP server: GHL MCP Server

Architecture

Transport: Streamable HTTP at /mcp, answering with application/json.

Tools

Records — list_records, get_record, create_records, update_records (PATCH + upsert), replace_records (PUT), delete_records (create/update/delete auto-batch in groups of 10)

Schema — list_bases, get_base_schema, create_base, create_table, update_table, create_field, update_field

Comments — list_comments, create_comment, update_comment, delete_comment

Webhooks — create_webhook, list_webhooks, delete_webhook, list_webhook_payloads, refresh_webhook, manage_webhook_notifications

Attachments — upload_attachment, download_attachment

User — whoami

The server ships a detailed instructions block so Claude picks the right tool and follows the correct sequence (resolve IDs → read/write) with minimal prompting.

How document upload works

open_upload_picker takes only a destination — base, record and attachment field. It has no parameter for file content. Calling it opens an in-chat file picker (an MCP App served as a ui:// resource); the user selects a file and the browser sends those exact bytes to /upload, authorized by a short-lived sealed ticket that names the destination. The Worker streams them to Airtable and drops them.

The model never touches the bytes, and that is the point:

• Tool arguments are produced by the model one character at a time, so base64 in an argument means typing ~1.4 MB per megabyte of file — past any response limit, so uploads stall and never arrive.

• Where a host hands the model an attached file as extracted text rather than raw bytes, the model cannot reproduce the original at all, and may generate a plausible-looking substitute. Removing the parameter makes that failure impossible.

If a host's iframe CSP blocks the direct POST, the widget falls back to relaying the bytes through the host into the internal connector_upload_attachment tool, which forwards them server-to-server. That path is capped near 3 MB by the MCP transport; the direct path supports the full 5 MB.

Uploading from a filesystem (Claude Code)

A picker is the wrong tool where the assistant can genuinely read the user's files — so the natural name belongs to the direct path. upload_attachment returns a ticket that the shell spends, so files go from disk to Airtable without their bytes entering the conversation, and a whole folder can be processed unattended:

curl -sS -X POST "https://airtable-mcp.3nuggets.io/upload" \
     -H "X-Upload-Ticket: <ticket>" \
     -F "file=@./invoices/march.pdf" -F "recordId=recXXXXXXXXXXXXXX"

Omit recordId when minting to get one ticket covering many records in the base; pass it to pin the ticket to a single record, after which a recordId in the request is ignored.

The two ticket kinds are sealed under different purposes, and that is the safety property rather than a matter of instructions. connector_upload_attachment opens picker tickets only, so a local ticket can never be spent through a tool call. A host with no filesystem may still request one, but has no shell to spend it with and no relay that will accept it — so an assistant that cannot see a real file has no route to upload an invented one either.

The ticket is a sealed blob like every other piece of state here — nothing is written down. It carries the caller's Airtable credential, is bound to one record and field so it cannot be redirected, and expires after 15 minutes.

File size limit

Airtable's API accepts at most 5 MB of file bytes per upload. Larger files can only be added through the Airtable UI. Airtable's alternative — having Airtable fetch a public URL — is deliberately not used here, because it would require staging the file in storage, which this server does not do.

Setup & deploy

Prerequisites

• Node.js 18+ and the Cloudflare Wrangler CLI, logged in (wrangler login).

• An Airtable account.

1. Install and deploy

npm install
npm run deploy

Note the URL, e.g. https://airtable-mcp-server.<your-subdomain>.workers.dev.

Optional — custom domain. If the domain is on your Cloudflare account, add a route to wrangler.jsonc and Wrangler creates the DNS record and certificate:

"routes": [{ "pattern": "airtable-mcp.example.com", "custom_domain": true }]

Defining routes disables the *.workers.dev URL unless you also set "workers_dev": true. Whichever hostname you settle on must match the OAuth redirect URL below.

2. Register an Airtable OAuth integration

Go to https://airtable.com/create/oauth → Register new OAuth integration.

• OAuth redirect URL: https://<your-worker-host>/callback

• Scopes: data.records:read, data.records:write, data.recordComments:read, data.recordComments:write, schema.bases:read, schema.bases:write, webhook:manage, user.email:read

• Copy the Client ID, then generate and copy the Client secret (shown once).

To let people other than yourself authorize it, Airtable also requires a Privacy policy URL and Terms of service URL on the integration.

3. Set secrets

npx wrangler secret put AIRTABLE_CLIENT_ID
npx wrangler secret put AIRTABLE_CLIENT_SECRET
npx wrangler secret put TOKEN_SEALING_KEY   # long random string, e.g. `openssl rand -hex 32`

4. Redeploy

npm run deploy

Connecting

• claude.ai → Settings → Connectors → Add custom connector → paste https://<your-worker-host>/mcp

• Claude Desktop → Settings → Connectors → same URL

• Claude Code → claude mcp add --transport http airtable https://<your-worker-host>/mcp

Then sign in with Airtable when prompted.

Local development

cp .dev.vars.example .dev.vars   # fill in secrets
npm run dev

License

MIT