airtable-mcp

Airtable MCP Server is an Airtable integration server for AI applications. Through Anthropic's Model Context Protocol (MCP), it connects Airtable data to AI clients, enabling developers to use natural language to query, create, update, and delete records, as well as manage bases, tables, and schemas. The current version is 5.1.0, based on the MCP 2026-07-28 specification, using the v2 TypeScript SDK (@modelcontextprotocol/server).

Purpose and Positioning This server is used to directly operate Airtable in AI clients that support MCP (such as Claude, Codex, Cursor, Windsurf, VS Code, etc.), covering scenarios such as record reading and writing, structure management, comments, Webhooks, batch processing, governance, and AI analysis.

Main Capabilities

• Full CRUD: Create, read, update, and delete records, with support for filtering and pagination.
• Record Comments: List, create, update, and delete comments on records.
• Schema Management: Programmatically create and modify tables, fields, and views.
• Batch Operations: Process up to 10 records at a time to improve performance.
• Webhook Management: Set up real-time notifications for data changes.
• Governance and Compliance: Allowlist governance, PII masking, and exception tracking.
• User Identity: Verify token identity through the whoami tool.
• AI Analysis: Provide 10 prompt templates for predictive analytics, natural language queries, and automated insights.
• Multi-Base Support: Dynamically discover and use multiple bases.
• Type Safety: Complete TypeScript type definitions.

Number of Tools The server provides a total of 42 tools, divided into: core operations (4), record CRUD (5), Upsert (2), Schema discovery (4), table management (3), field management (3), batch operations (3), Webhook management (5), views and attachments (3), Base management (3), record comments (4), user information (1), governance and administration (2).

Protocol and Transport

• Stateless Core: Each request is served by a brand-new server instance created by a shared factory, with no sessions and no sticky routing; in HTTP mode, any request can land on any replica, making it suitable for serverless and horizontally scaled environments.
• Dual Protocol Era: Simultaneously serves 2026-07-28 modern clients (per-request envelope) and 2025-era legacy clients (initialize handshake); under stdio, the protocol era is fixed per connection, while under HTTP, a stateless fallback is performed per request.
• Transport Methods: stdio (serveStdio) for local clients; setting PORT or MCP_HTTP_PORT enables streamable HTTP (createMcpHandler + Node adapter) and provides a /health endpoint.
• Tasks Extension: Intentionally not implemented; the specification has moved Tasks out of the core, and all operations on this server are sub-second Airtable API calls (batch limit 10), so background task semantics provide no benefit.

Usage

1. Claude Desktop: No installation required. Add the configuration to ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows and restart; npx will automatically download and run the server, with no need for git clone or npm install.
2. Claude Code: Provides a single-command installation script that checks prerequisites, prompts for the Airtable token, and writes to ~/.claude.json; the token can also be passed directly. The configuration is located under mcpServers in ~/.claude.json. The script uses a bash wrapper prefixed with cd /tmp && to avoid the edge case where npx resolves the binary in a directory containing a package.json with the same name.
3. Codex: Edit ~/.codex/config.toml (or .codex/config.toml for a trusted project); the Codex CLI, IDE extension, and ChatGPT desktop app share this configuration.
4. Cursor: Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project). Cursor's enablement for all serversThe total tool limit is 40, while this server exposes 42, so it is recommended to set AIRTABLE_TOOLSET=core, registering only 18 record-centric tools (read, write, batch, governance); if Airtable is the only MCP server, it can be omitted or set to full, and disabled per tool in Cursor's Tools & MCP settings. Note that Cursor only provides MCP tools in Agent and Plan modes (not in Ask/Edit), and consumes tools and resources but not MCP prompts.
5. Windsurf: add the same JSON block to ~/.codeium/windsurf/mcp_config.json (Cascade → MCP settings); supports per-tool toggling.
6. VS Code (GitHub Copilot agent mode): add to .vscode/mcp.json.
7. Compatible with any client: tool names use bare snake_case, are length-compliant, and contain no : or * (Cursor allowlist syntax server:tool reserved characters); logs are always written to stderr, not polluting stdout, to avoid stdio frame corruption.
8. Remote/HTTP clients: set PORT or MCP_HTTP_PORT to start the server, and point the client to http://host:port/mcp（可流式 HTTP, stateless; /health is for orchestrators).
9. Tool limit control: use AIRTABLE_TOOLSET=core or an explicit allowlist (e.g., AIRTABLE_TOOLSET=describe,query,list_records) to accommodate clients that limit the number of tools or to streamline agent context.

Prerequisites

• Node.js 20 or later (required by the MCP v2 SDK).
• An Airtable account and a Personal Access Token, created at airtable.com/create/tokens with all scopes listed in Token Scopes granted.
• Airtable Base ID (optional; can be omitted and dynamically discovered via the list_bases tool). The Base ID can be obtained from the URL when viewing a base https://airtable.com/[BASE_ID]/... .

Natural language interaction examples

• Basic operations: "List all Airtable bases I can access", "Show all records in the Projects table", "Create a task with priority High and due date tomorrow", "Update the status of task ID rec123 to Completed", "Search for records where Status equals Active".
• Schema management: "Show the full schema of this base", "Create a new table named Tasks with Name, Priority, and Due Date fields", "Add a Status field to the Projects table".
• Record comments: "Show all comments on rec123", "Add a comment to this record: Reviewed and approved", "Update my comment to Needs revision".
• Batch operations: "Create 5 new records at once in the Tasks table", "Batch update the status values of multiple records", "Delete these 3 records in one operation".
• Webhooks: "List all active webhooks in my base", "Create a webhook for changes in the Projects table".

Environment variables and project structure Environment variables are not required for ordinary users. Clone the repository only if you need to contribute to or modify the server; end users should use the npx method.

Limitations and notes

• Batch operations are limited to 10 records at a time.
• The Tasks extension in the 2026-07-28 specification is not currently implemented; if long-running tools are added in the future, this will be re-evaluated.
• Other environment variable details, complete tool parameter descriptions, the specific contents of AI prompt templates, and the detailed mechanisms of governance and compliance are not currently provided in the materials.

License and support The project uses the MIT License, see LICENSE for details. GitHub Discussions is provided for communication, along with a Code of conduct and Security policy. Contributions require opening an issue first to discuss major changes.