Skip to content
Back to search

airtable-mcp

Airtable integration for AI-powered applications via Anthropic's Model Context Protocol (MCP)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/rashidazarang--airtable-mcp/badge.svg)](/listings/rashidazarang--airtable-mcp)

HTML

<a href="/listings/rashidazarang--airtable-mcp"><img src="/api/listings/rashidazarang--airtable-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

No installation required — just add this to your Claude Desktop config and restart:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

{
  "mcpServers": {
    "airtable": {
      "command": "npx",
      "args": ["-y", "@rashidazarang/airtable-mcp"],
      "env": {
        "AIRTABLE_TOKEN": "YOUR_AIRTABLE_TOKEN",
        "AIRTABLE_BASE_ID": "YOUR_BASE_ID"
      }
    }
  }
}

That's it. `npx` downloads and runs the server automatically. No `git clone`, no `npm install`.

> **Get your token** at [airtable.com/create/tokens](https://airtable.com/create/tokens) — grant all scopes listed under [Token Scopes](#token-scopes) below. **Get your Base ID** from the URL when viewing your base: `https://airtable.com/[BASE_ID]/...` (or omit it and use `list_bases` to discover bases dynamically).

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 496 lines · 2 findings marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Airtable MCP Server
  2. [![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/rashidazarang/airtable-mcp)](https://archestra.ai/mcp-catalog/rashidazarang__airtable-mcp)
  3. [![smithery badge](https://smithery.ai/badge/@rashidazarang/airtable-mcp)](https://smithery.ai/server/@rashidazarang/airtable-mcp)
  4. ![Airtable](https://img.shields.io/badge/Airtable-18BFFF?style=for-the-badge&logo=Airtable&logoColor=white)
  5. [![MCP](https://img.shields.io/badge/MCP-5.1.0-blue)](https://github.com/rashidazarang/airtable-mcp)
  6. [![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue)](https://www.typescriptlang.org/)
  7. [![AI Agent](https://img.shields.io/badge/AI_Agent-Enhanced-purple)](https://github.com/rashidazarang/airtable-mcp)
  8. [![Security](https://img.shields.io/badge/Security-Enterprise-green)](https://github.com/rashidazarang/airtable-mcp)
  9. [![Protocol](https://img.shields.io/badge/Protocol-2026--07--28-success)](https://modelcontextprotocol.io/)
  10. A Model Context Protocol (MCP) server for Airtable with full CRUD operations, schema management, record comments, webhooks, batch operations, governance controls, and AI-powered analytics.
  11. **Version 5.1.0** | MCP Protocol 2026-07-28 (stateless core, legacy 2025-era clients still served) | Works with Claude, Codex, Cursor, Windsurf, VS Code, and any MCP client | [![npm](https://img.shields.io/npm/v/@rashidazarang/airtable-mcp)](https://www.npmjs.com/package/@rashidazarang/airtable-mcp)
  12. ---
  13. ## Quick Start (Claude Desktop)
  14. No installation required — just add this to your Claude Desktop config and restart:
  15. **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  16. **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  17. ```json
  18. {
  19. "mcpServers": {
  20. "airtable": {
  21. "command": "npx",
  22. "args": ["-y", "@rashidazarang/airtable-mcp"],
  23. "env": {
  24. "AIRTABLE_TOKEN": "YOUR_AIRTABLE_TOKEN",
  25. "AIRTABLE_BASE_ID": "YOUR_BASE_ID"
  26. }
  27. }
  28. }
  29. }
  30. ```
  31. That's it. `npx` downloads and runs the server automatically. No `git clone`, no `npm install`.
  32. > **Get your token** at [airtable.com/create/tokens](https://airtable.com/create/tokens) — grant all scopes listed under [Token Scopes](#token-scopes) below. **Get your Base ID** from the URL when viewing your base: `https://airtable.com/[BASE_ID]/...` (or omit it and use `list_bases` to discover bases dynamically).
  33. ---
  34. ## Quick Start (Claude Code)
  35. ### One-command install
  36. ```bash
  37. curl -fsSL https://raw.githubusercontent.com/rashidazarang/airtable-mcp/main/setup.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 51 on GitHub
  38. ```
  39. The script checks prerequisites, prompts for your Airtable token, and writes the MCP config to `~/.claude.json`. Restart Claude Code (or run `/mcp`) to connect.
  40. You can also pass your token directly:
  41. ```bash
  42. curl -fsSL https://raw.githubusercontent.com/rashidazarang/airtable-mcp/main/setup.sh | bash -s -- YOUR_AIRTABLE_TOKEN
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 59 on GitHub
  43. ```
  44. ### Manual config
  45. Add to `~/.claude.json` under `mcpServers`:
  46. ```json
  47. {
  48. "airtable": {
  49. "type": "stdio",
  50. "command": "/bin/bash",
  51. "args": ["-c", "cd /tmp && npx -y @rashidazarang/airtable-mcp"],
  52. "env": {
  53. "AIRTABLE_TOKEN": "YOUR_AIRTABLE_TOKEN"
  54. }
  55. }
  56. }
  57. ```
  58. > **Why the bash wrapper?** `npx` can fail to resolve the binary when run from a directory that contains a `package.json` with the same package name. The `cd /tmp &&` prefix avoids this edge case.
  59. ---
  60. ## Quick Start (Codex, Cursor, Windsurf, VS Code)
  61. The server works with any MCP client. It serves both the modern 2026-07-28 protocol and 2025-era clients automatically — no configuration needed for either.
  62. ### OpenAI Codex (CLI, IDE extension, ChatGPT desktop)
  63. One command:
  64. ```bash
  65. codex mcp add airtable -- npx -y @rashidazarang/airtable-mcp
  66. ```
  67. Or edit `~/.codex/config.toml` (or `.codex/config.toml` for a trusted project) directly:
  68. ```toml
  69. [mcp_servers.airtable]
  70. command = "npx"
  71. args = ["-y", "@rashidazarang/airtable-mcp"]
  72. [mcp_servers.airtable.env]
  73. AIRTABLE_TOKEN = "YOUR_AIRTABLE_TOKEN"
  74. ```
  75. The Codex CLI, IDE extension, and ChatGPT desktop app share this configuration.
  76. ### Cursor
  77. Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project):
  78. ```json
  79. {
  80. "mcpServers": {
  81. "airtable": {
  82. "command": "npx",
  83. "args": ["-y", "@rashidazarang/airtable-mcp"],
  84. "env": {
  85. "AIRTABLE_TOKEN": "YOUR_AIRTABLE_TOKEN",
  86. "AIRTABLE_TOOLSET": "core"
  87. }
  88. }
  89. }
  90. }
  91. ```
  92. > **Why `AIRTABLE_TOOLSET=core`?** Cursor caps agents at **40 enabled tools across all servers**, and this server exposes 42. The `core` profile registers the 18 record-centric tools (reads, writes, batches, governance), leaving room for other servers. Omit it (or set `full`) if Airtable is your only MCP server and you manage the cap by disabling individual tools in Cursor's *Tools & MCP* settings. Also note: Cursor offers MCP tools in **Agent** and **Plan** modes only (not Ask/Edit), and consumes tools and resources but not MCP prompts.
  93. ### Windsurf
  94. Add the same JSON block to `~/.codeium/windsurf/mcp_config.json` (Cascade → MCP settings). Windsurf supports per-tool toggling if you prefer the full toolset.
  95. ### VS Code (GitHub Copilot agent mode)
  96. Add to `.vscode/mcp.json`:
  97. ```json
  98. {
  99. "servers": {
  100. "airtable": {
  101. "type": "stdio",
  102. "command": "npx",
  103. "args": ["-y", "@rashidazarang/airtable-mcp"],
  104. "env": { "AIRTABLE_TOKEN": "YOUR_AIRTABLE_TOKEN" }
  105. }
  106. }
  107. }
  108. ```
  109. ### Compatibility notes (any client)
  110. - **Both protocol eras served** — modern 2026-07-28 clients and legacy 2025-era clients (Codex, Cursor, Windsurf, Cline, Zed, and most others today) negotiate automatically.
  111. - **Tool names are client-safe** — bare snake_case, well under length limits, and free of `:` and `*` (reserved by Cursor's allowlist grammar `server:tool`).
  112. - **Logs never touch stdout** — all logging goes to stderr, so stdio framing is never corrupted.
  113. - **Remote/HTTP clients** — start the server with `PORT` or `MCP_HTTP_PORT` set and point the client at `http://host:port/mcp` (streamable HTTP, stateless; `/health` for orchestrators).
  114. - **Tool caps** — use `AIRTABLE_TOOLSET=core` or an explicit allowlist (e.g. `AIRTABLE_TOOLSET=describe,query,list_records`) for clients that limit enabled tools or to slim the agent's context.
  115. ---
  116. ## Overview
  117. This server provides comprehensive Airtable integration through the Model Context Protocol, enabling natural language interactions with your Airtable data. It includes **42 tools** covering every Airtable PAT scope and **10 AI prompt templates** for intelligent analytics.
  118. ### Key Features
  119. - **Full CRUD Operations** — Create, read, update, and delete records with filtering and pagination
  120. - **Record Comments** — List, create, update, and delete comments on records
  121. - **Schema Management** — Create and modify tables, fields, and views programmatically
  122. - **Batch Operations** — Process up to 10 records per operation for improved performance
  123. - **Webhook Management** — Set up real-time notifications for data changes
  124. - **Governance & Compliance** — Allow-list governance, PII masking, and exception tracking
  125. - **User Identity** — Verify token identity with the `whoami` tool
  126. - **AI Analytics** — 10 prompt templates for predictive analytics, natural language queries, and automated insights
  127. - **Multi-Base Support** — Discover and work with multiple bases dynamically
  128. - **Type Safety** — Full TypeScript support with comprehensive type definitions
  129. ---
  130. ## Protocol Support
  131. Built on the **MCP 2026-07-28 specification** with the v2 TypeScript SDK (`@modelcontextprotocol/server`):
  132. - **Stateless core** — every request is served by a fresh server instance from a shared factory; no sessions, no sticky routing. In HTTP mode any request can land on any replica, so the server deploys cleanly to serverless and horizontally scaled environments.
  133. - **Both eras served** — modern 2026-07-28 clients (per-request envelope) and legacy 2025-era clients (`initialize` handshake) are handled by the same factory: per-connection era pinning over stdio, per-request stateless fallback over HTTP.
  134. - **Transports** — stdio (`serveStdio`) for local clients like Claude Desktop/Code, and streamable HTTP (`createMcpHandler` + Node adapter) when `PORT`/`MCP_HTTP_PORT` is set, with a `/health` endpoint for orchestrators.
  135. - **Tasks extension** — deliberately not implemented: the 2026-07-28 spec moved Tasks out of core into the `io.modelcontextprotocol/tasks` extension, and every operation this server exposes is a sub-second Airtable API call (batches are capped at 10 records), so background-task semantics add nothing. This will be revisited if long-running tools are added.
  136. ---
  137. ## Prerequisites
  138. - Node.js 20 or later (required by the MCP v2 SDK)
  139. - An Airtable account with a Personal Access Token
  140. - Your Airtable Base ID (optional — can be discovered via the `list_bases` tool)
  141. ---
  142. ## Token Scopes
  143. Create a Personal Access Token at [airtable.com/create/tokens](https://airtable.com/create/tokens) with these scopes:
  144. | Scope | Purpose |
  145. |-------|---------|
  146. | `data.records:read` | Read records |
  147. | `data.records:write` | Create, update, delete records |
  148. | `data.recordComments:read` | Read record comments |
  149. | `data.recordComments:write` | Create, update, delete comments |
  150. | `schema.bases:read` | View table schemas |
  151. | `schema.bases:write` | Create and modify tables and fields |
  152. | `user.email:read` | Read user identity (whoami) |
  153. | `webhook:manage` | Manage webhooks (optional) |
  154. ---
  155. ## Usage
  156. Once configured, interact with your Airtable data using natural language:
  157. ### Basic Operations
  158. - "List all my accessible Airtable bases"
  159. - "Show me all records in the Projects table"
  160. - "Create a new task with priority 'High' and due date tomorrow"
  161. - "Update the status of task ID rec123 to 'Completed'"
  162. - "Search for records where Status equals 'Active'"
  163. ### Schema Management
  164. - "Show me the complete schema for this base"
  165. - "Create a new table called 'Tasks' with Name, Priority, and Due Date fields"
  166. - "Add a Status field to the Projects table"
  167. ### Record Comments
  168. - "Show me all comments on record rec123"
  169. - "Add a comment to this record: 'Reviewed and approved'"
  170. - "Update my comment to say 'Needs revision'"
  171. ### Batch Operations
  172. - "Create 5 new records at once in the Tasks table"
  173. - "Update multiple records with new status values"
  174. - "Delete these 3 records in one operation"
  175. ### Webhooks
  176. - "List all active webhooks in my base"
  177. - "Create a webhook for changes to my Projects table"
  178. ---
  179. ## Available Tools (42)
  180. ### Core Operations (4 tools)
  181. | Tool | Description |
  182. |------|-------------|
  183. | `list_bases` | List all accessible bases with permissions |
  184. | `describe` | Describe base or table schema (supports detail levels) |
  185. | `query` | Query records with filtering, sorting, and pagination |
  186. | `search_records` | Advanced search with Airtable formulas |
  187. ### Record CRUD (5 tools)
  188. | Tool | Description |
  189. |------|-------------|
  190. | `list_records` | List records with field selection and pagination |
  191. | `get_record` | Retrieve a single record by ID |
  192. | `create` | Create new records (requires dryRun diff review) |
  193. | `update` | Update existing records (requires dryRun diff review) |
  194. | `delete_record` | Remove a record from a table |
  195. ### Upsert (2 tools)
  196. | Tool | Description |
  197. |------|-------------|
  198. | `upsert` | Update or create records based on merge fields |
  199. | `batch_upsert_records` | Batch upsert with merge-on fields |
  200. ### Schema Discovery (4 tools)
  201. | Tool | Description |
  202. |------|-------------|
  203. | `list_tables` | Get all tables in a base with schema info |
  204. | `get_base_schema` | Get complete schema for any base |
  205. | `list_field_types` | Reference guide for available field types |
  206. | `get_table_views` | List all views for a table |
  207. ### Table Management (3 tools)
  208. | Tool | Description |
  209. |------|-------------|
  210. | `create_table` | Create tables with custom field definitions |
  211. | `update_table` | Modify table names and descriptions |
  212. | `delete_table` | Remove tables (requires confirmation) |
  213. ### Field Management (3 tools)
  214. | Tool | Description |
  215. |------|-------------|
  216. | `create_field` | Add fields to existing tables |
  217. | `update_field` | Modify field properties and options |
  218. | `delete_field` | Remove fields (requires confirmation) |
  219. ### Batch Operations (3 tools)
  220. | Tool | Description |
  221. |------|-------------|
  222. | `batch_create_records` | Create up to 10 records at once |
  223. | `batch_update_records` | Update up to 10 records simultaneously |
  224. | `batch_delete_records` | Delete up to 10 records in one operation |
  225. ### Webhook Management (5 tools)
  226. | Tool | Description |
  227. |------|-------------|
  228. | `list_webhooks` | View all configured webhooks |
  229. | `create_webhook` | Set up real-time notifications |
  230. | `delete_webhook` | Remove webhook configurations |
  231. | `get_webhook_payloads` | Retrieve notification history |
  232. | `refresh_webhook` | Extend webhook expiration |
  233. ### Views & Attachments (3 tools)
  234. | Tool | Description |
  235. |------|-------------|
  236. | `create_view` | Create views (grid, form, calendar, etc.) |
  237. | `get_view_metadata` | Get view details including filters |
  238. | `upload_attachment` | Attach files from URLs |
  239. ### Base Management (3 tools)
  240. | Tool | Description |
  241. |------|-------------|
  242. | `create_base` | Create new bases with initial structure |
  243. | `list_collaborators` | View collaborators and permissions |
  244. | `list_shares` | List shared views and configurations |
  245. ### Record Comments (4 tools)
  246. | Tool | Description |
  247. |------|-------------|
  248. | `list_comments` | List comments on a record |
  249. | `create_comment` | Add a comment to a record |
  250. | `update_comment` | Edit an existing comment |
  251. | `delete_comment` | Remove a comment |
  252. ### User Info (1 tool)
  253. | Tool | Description |
  254. |------|-------------|
  255. | `whoami` | Get current user identity and scopes |
  256. ### Governance & Administration (2 tools)
  257. | Tool | Description |
  258. |------|-------------|
  259. | `list_governance` | Return governance allow-lists and PII masking policies |
  260. | `list_exceptions` | List recent exceptions and remediation proposals |
  261. ---
  262. ## AI Intelligence Suite
  263. Ten AI prompt templates for advanced analytics:
  264. | Prompt | Description |
  265. |--------|-------------|
  266. | `analyze_data` | Statistical analysis with anomaly detection |
  267. | `create_report` | Intelligent report generation |
  268. | `data_insights` | Business intelligence and pattern discovery |
  269. | `optimize_workflow` | Automation recommendations |
  270. | `smart_schema_design` | Database optimization suggestions |
  271. | `data_quality_audit` | Quality assessment and remediation |
  272. | `predictive_analytics` | Forecasting and trend prediction |
  273. | `natural_language_query` | Process questions with context awareness |
  274. | `smart_data_transformation` | AI-assisted data processing |
  275. | `automation_recommendations` | Workflow optimization with cost-benefit analysis |
  276. ---
  277. ## Advanced Configuration
  278. ### Smithery Cloud
  279. ```json
  280. {
  281. "mcpServers": {
  282. "airtable": {
  283. "command": "npx",
  284. "args": [
  285. "@smithery/cli",
  286. "run",
  287. "@rashidazarang/airtable-mcp"
  288. ],
  289. "env": {
  290. "AIRTABLE_TOKEN": "YOUR_TOKEN",
  291. "AIRTABLE_BASE_ID": "YOUR_BASE_ID"
  292. }
  293. }
  294. }
  295. }
  296. ```
  297. ### Environment Variables
  298. | Variable | Required | Description |
  299. |----------|----------|-------------|
  300. | `AIRTABLE_TOKEN` | Yes | Personal Access Token |
  301. | `AIRTABLE_BASE_ID` | No | Default base ID (discoverable via `list_bases`) |
  302. | `AIRTABLE_TOOLSET` | No | Which tools to register: `full` (default, all 42), `core` (18 record-centric tools — fits Cursor's 40-tool cap), or a comma-separated allowlist of tool names |
  303. | `LOG_LEVEL` | No | Logging level (default: `info`) |
  304. | `MCP_HTTP_PORT` | No | Enable HTTP transport for hosted deployments |
  305. ---
  306. ## Development
  307. > **Not required for users.** Clone the repo only if you want to contribute or modify the server. End users should use `npx` as shown in the Quick Start sections above.
  308. ```bash
  309. git clone https://github.com/rashidazarang/airtable-mcp.git
  310. cd airtable-mcp
  311. npm install
  312. npm run build
  313. ```
  314. ### Testing
  315. ```bash
  316. npm run test:types # Type checking
  317. npm test # Run test suite
  318. ```
  319. ### Project Structure
  320. ```
  321. airtable-mcp/
  322. ├── src/typescript/ # TypeScript implementation
  323. │ ├── app/
  324. │ │ ├── tools/ # 42 tool implementations
  325. │ │ ├── prompts/ # 10 AI prompt registrations
  326. │ │ ├── airtable-client.ts
  327. │ │ ├── governance.ts
  328. │ │ └── context.ts
  329. │ └── airtable-mcp-server.ts
  330. ├── dist/ # Compiled output
  331. ├── docs/ # Documentation
  332. ├── types/ # TypeScript definitions
  333. └── bin/ # CLI executables
  334. ```
  335. ---
  336. ## Troubleshooting
  337. **Connection Issues**
  338. - Verify the MCP server is running
  339. - Restart your MCP client
  340. - Check that your token has the required scopes
  341. **Invalid Token**
  342. - Verify your Personal Access Token is correct
  343. - Confirm the token has the required scopes
  344. - Check for extra whitespace in credentials
  345. **Base Not Found**
  346. - Confirm your Base ID is correct
  347. - Verify your token has access to the base
  348. - Use `list_bases` to discover accessible bases
  349. ---
  350. ## Documentation
  351. - [Changelog](docs/CHANGELOG.md)
  352. - [Release Notes](docs/releases/)
  353. ---
  354. ## Contributing
  355. Contributions are welcome. Please open an issue first to discuss major changes.
  356. ---
  357. ## License
  358. MIT License — see [LICENSE](LICENSE) for details.
  359. ---
  360. ## Support
  361. - [GitHub Issues](https://github.com/rashidazarang/airtable-mcp/issues)
  362. - [GitHub Discussions](https://github.com/rashidazarang/airtable-mcp/discussions)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.