Airtable MCP

Airtable MCP 服务

适用于 Airtable 的模型上下文协议（MCP）服务，支持完整的 CRUD 操作、架构管理、记录评论、Webhooks、批量操作、治理控制和 AI 驱动的分析。

版本 5.1.0 | MCP 协议 2026-07-28（无状态核心，仍兼容旧版 2025 年客户端）| 适用于 Claude、Codex、Cursor、Windsurf、VS Code 和任何 MCP 客户端 |

---

快速开始（Claude Desktop）

无需安装——只需将以下内容添加到 Claude Desktop 配置中并重启：

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"
      }
    }
  }
}

完成。npx 会自动下载并运行服务。无需 git clone，也无需 npm install。

获取令牌：前往 airtable.com/create/tokens，授予下方令牌作用域中列出的所有权限。获取 Base ID：查看 Base 时，可从 URL 中获取：https://airtable.com/[BASE_ID]/...（也可以省略它，并使用 list_bases 动态查找 Base）。

---

快速开始（Claude Code）

一键安装

curl -fsSL https://raw.githubusercontent.com/rashidazarang/airtable-mcp/main/setup.sh | bash

该脚本会检查前置条件、提示输入 Airtable 令牌，并将 MCP 配置写入 ~/.claude.json。重启 Claude Code（或运行 /mcp）即可连接。

也可以直接传入令牌：

curl -fsSL https://raw.githubusercontent.com/rashidazarang/airtable-mcp/main/setup.sh | bash -s -- YOUR_AIRTABLE_TOKEN

手动配置

在 ~/.claude.json 的 mcpServers 下添加：

{
  "airtable": {
    "type": "stdio",
    "command": "/bin/bash",
    "args": ["-c", "cd /tmp && npx -y @rashidazarang/airtable-mcp"],
    "env": {
      "AIRTABLE_TOKEN": "YOUR_AIRTABLE_TOKEN"
    }
  }
}

为什么使用 bash 包装器？ 如果在包含同名 package.json 的目录中运行，npx 可能无法解析二进制文件。cd /tmp && 前缀可以避免这种边缘情况。

---

快速开始（Codex、Cursor、Windsurf、VS Code）

该服务适用于任何 MCP 客户端。它会自动同时支持现代 2026-07-28 协议和 2025 年客户端——两者都无需配置。

OpenAI Codex（CLI、IDE 扩展、ChatGPT 桌面应用）

运行一条命令：

codex mcp add airtable -- npx -y @rashidazarang/airtable-mcp

也可以直接编辑 ~/.codex/config.toml（或受信任项目中的 .codex/config.toml）：

[mcp_servers.airtable]
command = "npx"
args = ["-y", "@rashidazarang/airtable-mcp"]

[mcp_servers.airtable.env]
AIRTABLE_TOKEN = "YOUR_AIRTABLE_TOKEN"

Codex CLI、IDE 扩展和 ChatGPT 桌面应用共用此配置。

Cursor

添加到 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（按项目）：

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

为什么设置 AIRTABLE_TOOLSET=core？ Cursor 将 Agent 可用工具数限制为所有服务合计 40 个，而此服务提供 42 个工具。core 配置注册以记录为核心的 18 个工具（读取、写入、批处理、治理），为其他服务留出空间。如果 Airtable 是你唯一的 MCP 服务，并且你通过在 Cursor 的 Tools & MCP 设置中禁用单个工具来控制数量上限，也可以省略此设置（或设为 full）。另请注意：Cursor 仅在 Agent 和 Plan 模式下提供 MCP 工具（不包括 Ask/Edit），并且会使用工具和资源，但不会使用 MCP 提示词。

Windsurf

将相同的 JSON 代码块添加到 ~/.codeium/windsurf/mcp_config.json（Cascade → MCP 设置）。如果更喜欢使用完整工具集，Windsurf 支持逐个切换工具。

VS Code（GitHub Copilot Agent 模式）

添加到 .vscode/mcp.json：

{
  "servers": {
    "airtable": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@rashidazarang/airtable-mcp"],
      "env": { "AIRTABLE_TOKEN": "YOUR_AIRTABLE_TOKEN" }
    }
  }
}

兼容性说明（适用于任何客户端）

• 支持两代协议 — 新版 2026-07-28 客户端和旧版 2025 年客户端（Codex、Cursor、Windsurf、Cline、Zed，以及如今大多数其他客户端）均可自动协商。
• 工具名称兼容客户端 — 使用不带前缀的 snake_case，长度远低于限制，且不含 : 和 *（Cursor 的允许列表语法 server:tool 将它们保留为特殊字符）。
• 日志不会写入 stdout — 所有日志均写入 stderr，因此不会破坏 stdio 分帧。
• 远程/HTTP 客户端 — 设置 PORT 或 MCP_HTTP_PORT 后启动服务，并将客户端指向 http://host:port/mcp（无状态的可流式 HTTP；编排器可使用 /health）。
• 工具上限 — 对于限制已启用工具数量的客户端，或想精简 Agent 上下文时，可使用 AIRTABLE_TOOLSET=core 或显式允许列表（例如 AIRTABLE_TOOLSET=describe,query,list_records）。

---

概述

此服务通过模型上下文协议提供全面的 Airtable 集成，让你能够使用自然语言与 Airtable 数据交互。其中包括 42 个工具，覆盖 Airtable 的所有 PAT 权限范围，以及用于智能分析的 10 个 AI 提示词模板。

主要功能

• 完整的 CRUD 操作 — 创建、读取、更新和删除记录，并支持筛选和分页
• 记录评论 — 列出、创建、更新和删除记录上的评论
• 架构管理 — 以编程方式创建和修改表、字段及视图
• 批量操作 — 每次操作最多处理 10 条记录，提升性能
• Webhook 管理 — 为数据变更设置实时通知
• 治理与合规 — 允许列表治理、PII 屏蔽和异常跟踪
• 用户身份 — 使用 whoami 工具验证令牌身份
• AI 分析 — 提供 10 个提示词模板，用于预测分析、自然语言查询和自动化洞察
• 多 Base 支持 — 动态发现并使用多个 Base
• 类型安全 — 提供完整的 TypeScript 支持和全面的类型定义

---

协议支持

基于 MCP 2026-07-28 规范和 v2 TypeScript SDK（@modelcontextprotocol/server）构建：

• 无状态核心 — 每个请求都由共享工厂创建的全新服务实例处理；没有会话，也无需粘性路由。在 HTTP 模式下，任何请求都可以发送到任意副本，因此该服务可以轻松部署到无服务器和水平扩展环境中。
• 支持两代协议 — 同一工厂可处理新版 2026-07-28 客户端（逐请求封装）和旧版 2025 年客户端（initialize 握手）：stdio 连接会固定使用协商的协议版本，HTTP 则采用逐请求的无状态回退机制。
• 传输方式 — 本地客户端（如 Claude Desktop/Code）使用 stdio（serveStdio）；设置 PORT/MCP_HTTP_PORT 时使用可流式 HTTP（createMcpHandler + Node 适配器），并为编排器提供 /health 端点。
• Tasks 扩展 — 暂不实现：2026-07-28 规范将 Tasks 从核心移至 io.modelcontextprotocol/tasks 扩展，而此服务提供的每项操作都是耗时不到一秒的 Airtable API 调用（每批最多 10 条记录），因此后台任务语义并无额外价值。如果日后添加长时间运行的工具，我们会重新评估。

---

前置条件

• Node.js 20 或更高版本（MCP v2 SDK 的要求）
• Airtable 账号和个人访问令牌
• 你的 Airtable Base ID（可选 — 可通过 list_bases 工具发现）

---

令牌权限范围

在 airtable.com/create/tokens 创建个人访问令牌，并授予以下权限范围：

权限范围	用途
data.records:read	读取记录
data.records:write	创建、更新、删除记录
data.recordComments:read	读取记录评论
data.recordComments:write	创建、更新、删除评论
schema.bases:read	查看表结构
schema.bases:write	创建和修改表及字段
user.email:read	读取用户身份信息（whoami）
webhook:manage	管理 Webhook（可选）

---

用法

配置完成后，使用自然语言与 Airtable 数据交互：

基本操作

• “列出我有权访问的所有 Airtable 基础”
• “显示 Projects 表中的所有记录”
• “创建一个优先级为‘High’、截止日期为明天的新任务”
• “将 ID 为 rec123 的任务状态更新为‘Completed’”
• “搜索 Status 等于‘Active’的记录”

结构管理

• “显示此基础的完整结构”
• “创建一个名为‘Tasks’的新表，包含 Name、Priority 和 Due Date 字段”
• “向 Projects 表添加 Status 字段”

记录评论

• “显示记录 rec123 上的所有评论”
• “为此记录添加评论：‘Reviewed and approved’”
• “将我的评论更新为‘Needs revision’”

批量操作

• “一次在 Tasks 表中创建 5 条新记录”
• “用新的状态值更新多条记录”
• “一次操作删除这 3 条记录”

Webhook

• “列出我基础中的所有活动 Webhook”
• “为 Projects 表的变更创建 Webhook”

---

可用工具（42）

核心操作（4 个工具）

工具	描述
list_bases	列出所有可访问的基础及其权限
describe	描述基础或表结构（支持详细程度设置）
query	使用筛选、排序和分页查询记录
search_records	使用 Airtable 公式进行高级搜索

记录增删改查（5 个工具）

工具	描述
list_records	根据字段选择和分页列出记录
get_record	按 ID 获取单条记录
create	创建新记录（需要通过 dryRun 差异审查）
update	更新现有记录（需要通过 dryRun 差异审查）
delete_record	从表中移除一条记录

插入或更新（2 个工具）

工具	描述
upsert	根据合并字段更新或创建记录
batch_upsert_records	根据合并字段批量插入或更新记录

结构发现（4 个工具）

工具	描述
list_tables	获取基础中的所有表及其结构信息
get_base_schema	获取任意基础的完整结构
list_field_types	可用字段类型参考指南
get_table_views	列出表的所有视图

表管理（3 个工具）

工具	描述
create_table	使用自定义字段定义创建表
update_table	修改表名和描述
delete_table	移除表（需要确认）

字段管理（3 个工具）

工具	描述
create_field	向现有表添加字段
update_field	修改字段属性和选项
delete_field	移除字段（需要确认）

批量操作（3 个工具）

工具	描述
batch_create_records	一次创建最多 10 条记录
batch_update_records	同时更新最多 10 条记录
batch_delete_records	一次操作删除最多 10 条记录

Webhook 管理（5 个工具）

工具	描述
list_webhooks	查看所有已配置的 webhook
create_webhook	设置实时通知
delete_webhook	移除 webhook 配置
get_webhook_payloads	获取通知历史记录
refresh_webhook	延长 webhook 的有效期

视图与附件（3 个工具）

工具	描述
create_view	创建视图（网格、表单、日历等）
get_view_metadata	获取视图详情，包括筛选条件
upload_attachment	从 URL 附加文件

Base 管理（3 个工具）

工具	描述
create_base	创建包含初始结构的新 Base
list_collaborators	查看协作者及权限
list_shares	列出已共享的视图和配置

记录评论（4 个工具）

工具	描述
list_comments	列出记录上的评论
create_comment	为记录添加评论
update_comment	编辑现有评论
delete_comment	移除评论

用户信息（1 个工具）

工具	描述
whoami	获取当前用户身份和权限范围

治理与管理（2 个工具）

工具	描述
list_governance	返回治理允许列表和 PII 掩码策略
list_exceptions	列出近期异常和补救方案

---

AI 智能套件

十个用于高级分析的 AI 提示词模板：

提示词	描述
analyze_data	统计分析与异常检测
create_report	智能生成报告
data_insights	商业智能与模式发现
optimize_workflow	自动化建议
smart_schema_design	数据库优化建议
data_quality_audit	质量评估与补救
predictive_analytics	预测与趋势预判
natural_language_query	结合上下文理解处理问题
smart_data_transformation	AI 辅助数据处理
automation_recommendations	通过成本效益分析优化工作流

---

高级配置

Smithery Cloud

{
  "mcpServers": {
    "airtable": {
      "command": "npx",
      "args": [
        "@smithery/cli",
        "run",
        "@rashidazarang/airtable-mcp"
      ],
      "env": {
        "AIRTABLE_TOKEN": "YOUR_TOKEN",
        "AIRTABLE_BASE_ID": "YOUR_BASE_ID"
      }
    }
  }
}

环境变量

变量	必填	描述
AIRTABLE_TOKEN	是	个人访问令牌
AIRTABLE_BASE_ID	否	默认 Base ID（可通过 list_bases 查找）
AIRTABLE_TOOLSET	否	要注册的工具：full（默认，全部 42 个）、core（18 个以记录为中心的工具，适用于 Cursor 的 40 个工具上限），或以逗号分隔的工具名称允许列表
LOG_LEVEL	否	日志级别（默认：info）
MCP_HTTP_PORT	否	为托管部署启用 HTTP 传输

---

开发

用户无需进行此操作。 只有在希望贡献代码或修改服务时才克隆仓库。终端用户应使用上方“快速开始”部分所示的 npx。

git clone https://github.com/rashidazarang/airtable-mcp.git
cd airtable-mcp
npm install
npm run build

测试

npm run test:types     # Type checking
npm test               # Run test suite

项目结构

airtable-mcp/
├── src/typescript/          # TypeScript implementation
│   ├── app/
│   │   ├── tools/           # 42 tool implementations
│   │   ├── prompts/         # 10 AI prompt registrations
│   │   ├── airtable-client.ts
│   │   ├── governance.ts
│   │   └── context.ts
│   └── airtable-mcp-server.ts
├── dist/                    # Compiled output
├── docs/                    # Documentation
├── types/                   # TypeScript definitions
└── bin/                     # CLI executables

---

故障排除

连接问题

• 确认 MCP 服务正在运行
• 重启 MCP 客户端
• 检查令牌是否具有所需权限范围

令牌无效

• 确认个人访问令牌正确无误
• 确认令牌具有所需权限范围
• 检查凭据中是否有多余空格

未找到 Base

• 确认 Base ID 正确无误
• 确认令牌有权访问该 Base
• 使用 list_bases 查找可访问的 Base

---

文档

• 更新日志
• 发行说明

---

贡献

欢迎贡献。请先提交 issue，讨论重大变更。

---

许可证

MIT 许可证 — 详情请参阅 LICENSE。

---

Support

• GitHub Issues
• GitHub Discussions