Airtable Mcp Server

---

主要功能

功能	说明	文件类型
公式编辑器	语法高亮、智能感知、美化 / 压缩	.formula、.min.formula
脚本编辑器	自动补全、悬停文档、诊断	.ats、.script
自动化编辑器	自动补全、悬停文档、诊断	.ata、.automation
MCP 服务（72 个工具 + manage_tools）	完整的 Airtable 内部 API — 架构、视图、字段、记录、扩展、模板	—
语言服务（LSP）	独立的多编辑器支持 — Neovim、Zed、Helix、OpenCode	以上所有类型
IDE 自动设置	一键配置 Cursor、Windsurf、Claude Desktop、Cline、Amp 的 MCP	—
AI 技能	为 AI 编码助手预先构建的 Airtable 专属规则和工作流	—
守护进程 + 隧道	持续运行的后台服务；可选通过 Cloudflare 或 ngrok 远程访问	—
工具配置	read-only（12 个工具）/ safe-write（54 个工具）/ full（72 个工具）/ custom 权限范围	—
操作系统密钥链身份验证	通过浏览器登录 Airtable，支持 SSO/2FA — 凭据存储在操作系统密钥链中	—

为什么要开发它

Airtable 的公共 Web API 一直未提供构建者实际最常需要的一些功能：创建公式字段、调整视图的筛选条件、安装扩展，或在公式导致生产环境故障前对其进行验证。官方 Airtable MCP 服务只是对同一 REST API 的薄封装，因此也存在这些缺陷。

**airtable-user-mcp 是官方 Airtable MCP 的附加组件，并非替代品。**它使用 Airtable 自己的内部 API（即 Web UI 使用的 API），覆盖 REST API 无法触及的功能范围。在 AI 客户端中同时注册这两项服务，助手就能获得完整的 Airtable 自动化体验——通过官方 MCP 使用 HTTP 处理记录，并通过此服务管理架构、公式、视图和扩展。

---

airtable-user-mcp 在官方 Airtable MCP 基础上新增的功能

这是一份功能覆盖对照表，而不是“二选一”的决策指南——两个服务互为补充，设计上可以并行运行。

功能	官方 Airtable MCP	airtable-user-mcp
工具总数	~17	73（72 + manage_tools）
认证方式	个人访问令牌或 OAuth，需按范围配置	使用常规 Airtable 账号登录一次即可（支持 SSO/2FA）
传输方式	HTTP（远程）	stdio（本地、私密）
数据绝不离开你的设备	❌ 请求经由 mcp.airtable.com	✅ 在本地直接调用 Airtable API
读取架构（bases、表、字段、视图）	部分支持（无视图配置）	完整支持——筛选、排序、分组、可见性、行高、描述
读取记录并解析字段值	部分支持	✅ query_records——完整解析查找、汇总和公式字段
按文本搜索记录（包括查找字段）	❌ filterByFormula 搭配 FIND()/SEARCH() 在查找字段上会静默失败	✅ query_records.search——对所有已解析值进行子字符串匹配
复制记录	❌	✅ duplicate_records
创建公式字段	❌ UNSUPPORTED_FIELD_TYPE_FOR_CREATE	✅
创建汇总字段	❌	✅
创建查找 / multipleLookupValues 字段	❌	✅
创建计数字段	❌	✅
更新现有字段的公式文本	❌	✅
应用公式前验证公式	❌	✅
重命名 / 复制 / 安全删除字段	部分支持（不能复制，也不提供依赖项摘要）	✅ 支持 expectedName 防护 + 依赖项预览
创建视图（网格/表单/看板/日历/图库/甘特图/列表）	❌（API 没有创建视图的端点）	✅
设置/追加视图筛选条件（嵌套 AND/OR）	❌	✅
设置视图排序	❌	✅
设置视图分组	❌	✅
更改列顺序	❌	✅
在视图中显示/隐藏列	❌	✅
更改行高	❌	✅
复制视图及其完整配置	❌	✅
视图描述、单元格换行、封面、颜色配置、日历日期、冻结列	❌	✅
侧边栏分区（创建、重命名、移动、删除）	❌	✅
记录模板（创建、预填、复制、应用、删除）	❌	✅
表单元数据（描述、重定向、归属信息、品牌设置）	❌	✅
扩展 / 区块管理（安装、启用、重命名、复制、移除）	❌	✅
创建仪表板页面	❌	✅
守护进程自诊断（会话失效？浏览器繁忙？守护进程退出？）	❌	✅ manage_daemon action=status，还支持启动 / 重启 / 停止 / 隧道 / 令牌轮换
工具配置档案和逐工具开关	❌	✅ 只读（12）/ 安全写入（54）/ 完整（72）/ 自定义
破坏性操作安全防护	依赖令牌范围	✅ expectedName 匹配、依赖项摘要、force 标志
批量创建记录限制	每次请求 10 条	使用相同的 Airtable 限制；不额外增加限制
VS Code / Cursor / Windsurf / Cline / Amp 一键安装	每个 IDE 都要手动编辑 JSON	✅ 通过配套扩展一键安装
带 IntelliSense 的公式编辑器	❌	✅（VS Code 扩展）
凭据存储	由你管理 PAT	OS 钥匙串，自动刷新
套餐要求	需使用支持 API 访问并可配置令牌范围的 Airtable 套餐	任何可登录的套餐
价格	免费	免费，MIT

来源：Airtable 官方 MCP 文档、Airtable Web API 参考，以及 关于 UNSUPPORTED_FIELD_TYPE_FOR_CREATE 的汇总字段讨论帖。

---

一起使用两个 MCP

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

airtable-user-mcp 是附加服务。按照 Airtable 的设置指南注册官方 Airtable MCP，然后在同一个 mcpServers 块中将它与本服务一起添加：

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

你的 MCP 客户端会提供两个服务中的所有工具。这两个条目彼此独立——可根据工作流需要任意重命名键（airtable、airtable-official、airtable-user-mcp 等）。

---

本仓库包含什么

这个单体仓库从同一源代码树中提供 三款产品：

---

演示

---

功能

MCP 服务（72 个工具 + manage_tools）

管理 Airtable 数据库，支持官方 REST API 不提供的功能：

类别	工具	亮点
架构读取	11	全面检查架构——数据库、表、字段、视图、侧边栏分区、记录模板；将所有公式字段下载到本地文件
记录读取	1	query_records——每次调用最多读取 1 000 条记录，并解析字段值；search 参数可用于查找字段和汇总字段（REST API 的 filterByFormula 不支持）
记录写入	4	create_records / update_records / duplicate_records / upload_attachment（这是通过 URL 写入 multipleAttachments 单元格的唯一方式）
记录删除	1	delete_records——批量删除表中的记录
表管理	3	创建 / 重命名 / 删除表
字段管理	9	创建公式 / 汇总 / 查找 / 计数字段，验证公式，更新描述，单个或批量删除
视图配置	20	筛选、排序、分组、列、冻结、行高、封面、颜色规则、日历日期、创建 / 复制 / 重命名 / 删除
侧边栏分区	4	创建、重命名、移入分区、删除（会自动将其中的视图提升为未分组视图）
记录模板	8	创建 / 重命名 / 描述 / 设置单元格 / 设置列 / 复制 / 应用 / 删除已保存的行框架
表单元数据	2	描述、重定向 URL、归属信息、复制给受访者、品牌设置（旧版表单视图）
扩展管理	7	创建、安装、启用/禁用、重命名、复制、移除扩展
工具管理	1	列出配置文件、切换配置文件、切换工具/类别（元工具，始终启用，不属于任何配置文件）
数据库同步	1	sync_base——将一个数据库的架构、视图和记录复制到另一个数据库。mode=plan/diff/status 为只读；mode=apply 会修改目标数据库，并且在设置 policy=mirror 并启用确认标志后，可删除表、字段、视图、分区和记录；mode=reconcile 会更新本地映射状态。具备漂移防护，并可通过日志恢复。
守护进程控制	1	manage_daemon——action=status 是只读自诊断：守护进程存活状态、传输方式、运行时长、隧道 URL，以及实时会话状态（会话失效、Airtable 最近一次熔断响应正文、浏览器忙碌队列），帮助区分“守护进程已退出”“会话已失效”和“浏览器忙碌”。还支持 start / restart / stop / tunnel_enable / tunnel_disable / token_rotate。仅限 full 配置文件。

请参阅完整工具参考文档 packages/mcp-server/README.md。

一个共享守护进程

扩展会在工具调用需要时启动共享 MCP 守护进程，因此所有 VS Code 窗口使用同一个 Airtable 浏览器会话，而不是每个窗口各用一个——这种重复正是大多数“会话已失效”错误的原因。 从仪表板停止的守护进程会保持停止状态；如果无法启动，扩展会回退到每窗口一个服务的模式，确保工具仍可使用。

由于守护进程通常处于运行状态，同一台机器上的其他 MCP 客户端（Claude Desktop、Cursor、Cline、Amp） 会连接到该守护进程，因此使用它的认证模式和 HTTP 客户端，而不是各自的配置——这是有意为之，因为 在同一个 Airtable 配置文件上运行两个浏览器会导致崩溃。每个此类客户端都会输出一行 stderr 信息说明这一点。请参阅 在客户端之间共享一个守护进程。

LSP 服务

airtable-user-lsp 是一款独立的语言服务器，可用于 Airtable 公式、脚本和自动化文件，适用于任何支持 LSP 的编辑器，不限于 VS Code。

# stdio mode — works standalone, no daemon needed
npx airtable-user-lsp --stdio

功能：为 .formula、.ats 和 .ata 文件提供诊断、补全、悬停文档和签名帮助。

守护进程运行时，会自动启动 airtable-user-lsp --tcp，让多个编辑器共享同一个语言服务器实例。TCP 端口会写入 ~/.airtable-user-mcp/daemon.lock 中的 port_lsp 字段。

各编辑器（Neovim、Zed、OpenCode、Helix）的配置请参阅 packages/lsp-server/README.md。

---

支持的 IDE

此扩展会为所有主流的 AI 编辑器自动配置 MCP：

不使用 VS Code？ 可直接使用独立的 MCP 服务：

npx airtable-user-mcp

---

查找我们

---

要求

• VS Code ^1.100.0（或任何提供 McpServerDefinitionProvider API 的分支版本）
• Node.js — 通过 VS Code 运行时捆绑提供；无需单独安装
• Google Chrome（或 Edge / Chromium）— Airtable 登录流程会在无头模式下使用 Patchright。在 Windows 上会回退到 msedge，在 Linux 上会回退到 chromium。如果未检测到受支持的浏览器，扩展会显示可操作的警告。

---

开发

这是一个 pnpm monorepo。

包	描述
packages/extension	VS Code 扩展宿主（TypeScript + tsup）
packages/webview	React 仪表板 webview（Vite + Tailwind v4）
packages/shared	共享类型和消息协议
packages/mcp-server	airtable-user-mcp — ESM Node MCP 服务
packages/lsp-server	airtable-user-lsp — 用于公式 / 脚本 / 自动化文件的 LSP 服务
scripts/	构建工具（esbuild 打包器、依赖打包）

pnpm install          # install all packages
pnpm build            # build shared → webview → mcp bundle → extension
pnpm package          # build + create airtable-formula-X.Y.Z.vsix
pnpm test             # run all unit tests
pnpm dev              # start webview dev server (browser preview)

MCP 服务的打包方式： scripts/bundle-mcp.mjs 使用 esbuild 将 packages/mcp-server/src/ 打包到 packages/extension/dist/mcp/。随后，scripts/prepare-package-deps.mjs 会在运行 vsce package 之前，将 patchright、patchright-core、otpauth、impit 和 @ngrok/ngrok 打包到 dist/node_modules/，因此安装后的扩展在运行时无需执行 npm install。

特定平台的 VSIX。 impit（Chrome-TLS HTTP 客户端）和 @ngrok/ngrok（ngrok 隧道提供商）将编译后的原生二进制文件分别保存在各平台的 npm 包中，而且只会安装与构建机器匹配的那个包。因此，单个 VSIX 无法包含适用于所有平台的可用原生二进制文件。我们改为每个平台发布一个 VSIX，每个 VSIX 仅打包该平台自己的二进制文件——VS Code 和 Open VSX 会为每位用户提供与其机器匹配的构建版本。支持的目标平台：

目标平台	impit	@ngrok/ngrok
win32-x64	impit-win32-x64-msvc	@ngrok/ngrok-win32-x64-msvc
win32-arm64	impit-win32-arm64-msvc	@ngrok/ngrok-win32-arm64-msvc
darwin-x64	impit-darwin-x64	@ngrok/ngrok-darwin-x64
darwin-arm64	impit-darwin-arm64	@ngrok/ngrok-darwin-arm64
linux-x64	impit-linux-x64-gnu	@ngrok/ngrok-linux-x64-gnu
linux-arm64	impit-linux-arm64-gnu	@ngrok/ngrok-linux-arm64-gnu
alpine-x64	impit-linux-x64-musl	@ngrok/ngrok-linux-x64-musl
alpine-arm64	impit-linux-arm64-musl	@ngrok/ngrok-linux-arm64-musl

不发布 linux-armhf（32 位 ARM）：impit 不提供 arm-gnueabihf 构建版本，因此 armhf VSIX 会声明 airtableFormula.mcp.httpClient: "impit"，随后报错 "Cannot find native binding"。基于相同原因，也不发布不限定目标平台的回退版本。

平台矩阵仅在 scripts/vsix-targets.mjs 中定义一次；版本和 tarball 哈希固定在 pnpm-lock.yaml 中。scripts/package-targets.mjs 会构建每个目标平台，scripts/assert-vsix-binaries.mjs 则会验证每个构件只包含其自身平台的 .node 文件，不含其他平台的文件——并按 scripts/native-binary-digests.json 中的 SHA-256 摘要进行逐字节校验；这些摘要来自已依据 pnpm-lock.yaml 的完整性哈希验证过的 tarball。文件名、package.json 中的 os / cpu 以及魔数，都是构件携带的标记，无法区分 x64 二进制文件和 ARM64 二进制文件，也无法区分 glibc 构建和 musl 构建；只有精确摘要能够做到。

这总共是八项目标构件打包 / 断言冒烟测试——在一台机器上构建八个 .vsix 文件并验证其内容。它们不是对八种原生绑定进行的运行时冒烟测试：任何单台主机都只能加载为自身编译的绑定，因此只有主机目标平台的绑定会经过真实的运行时加载。通过精确内容验证其余七个构件，是单主机构建能够对它们做出的最有力保证。

独立 npm 包 airtable-user-mcp 不受影响，仍然是通用版本——npm 会在安装时为你自己的机器解析正确的可选依赖。

---

支持本项目

本项目在 AI 编码工具的帮助下构建和维护。如果你觉得它有用，并希望支持后续开发（新工具、更新、错误修复），可以赠送 Claude Code 额度——这是构建本项目时使用的主要工具。

感兴趣吗？创建一个 issue，或联系我们讨论功能请求和赞助事宜。

---

许可证

MIT