Airtable MCP 服务器

🤖 革命性AI代理v3.2.5 - 先进的AI驱动Airtable MCP服务器，具有修复的TypeScript架构、世界级项目组织、全面智能能力、预测分析和企业自动化功能。

🚀 最新版本：v3.2.5 - 可选Base ID与增强多Base支持

重大改进，完全向后兼容：

• 🔓 可选Base ID - 启动时无需指定base，使用list_bases工具发现
• 🔍 增强Base发现 - 全新TypeScript实现的list_bases工具
• 🎯 动态Base选择 - 每次工具调用可指定base ID，无需启动时要求
• ✅ 修复问题#9 - 解决"启动时需要base"的限制
• 🔧 改进治理 - 智能base允许列表处理，支持多base工作流
• 📦 完整STDIO支持 - 确认与Claude桌面版/代码兼容

📋 上一版本：v3.2.4 - XSS安全修复与全面保护

重大改进，完全向后兼容：

• 🔧 修复TypeScript架构 - 解决编译问题，正确分离类型与运行时代码
• 📁 世界级组织 - 重构项目结构为src/typescript、src/javascript、src/python
• 🔒 完整安全修复 - 通过全面验证完全解决命令注入漏洞
• 🔷 TypeScript实现 - 完整类型安全服务器，严格验证
• 📘 全面类型定义 - 所有33个工具和10个AI提示完全类型化
• 🛡️ 编译时安全 - 通过高级类型检查在运行前捕获错误
• 🎯 开发者体验 - IntelliSense、自动完成和重构支持
• 🔄 双重分发 - 可选择使用JavaScript或TypeScript

🤖 AI智能套件

完整AI驱动智能，具备企业能力：

• 🤖 10个AI提示模板 - 高级分析、预测和自动化
• 🔮 预测分析 - 带置信区间的预测和趋势分析
• 🗣️ 自然语言处理 - 使用人类语言查询数据
• 📊 商业智能 - 自动化洞察与推荐
• 🏗️ 智能架构设计 - AI优化的数据库架构
• ⚡ 工作流自动化 - 智能流程优化
• 🔍 数据质量审计 - 全面质量评估与修复
• 📈 统计分析 - 带显著性测试的高级分析

✨ 功能特性

• 🔍 自然语言查询 - 用简单英语提问数据问题
• 📊 完整CRUD操作 - 创建、读取、更新和删除记录
• 🪝 Webhook管理 - 创建和管理实时通知的webhook
• 🏗️ 高级架构管理 - 创建表、字段和管理base结构
• 🔍 Base发现 - 探索所有可访问的base及其架构
• 🔧 字段管理 - 编程方式添加、修改和删除字段
• 🔐 安全认证 - 使用环境变量存储凭证
• 🚀 简易安装 - 提供多种安装选项
• ⚡ 快速可靠 - 基于Node.js构建，性能优异
• 🎯 33个强大工具 - 完整覆盖Airtable API，支持批量操作
• 📎 附件管理 - 通过URL上传文件到附件字段
• ⚡ 批量操作 - 单次创建、更新、删除最多10条记录
• 👥 协作工具 - 管理base协作者和共享视图
• 🤖 AI集成 - 智能数据操作的提示和采样
• 🔐 企业安全 - OAuth2、速率限制、全面验证

📋 先决条件

• 系统已安装Node.js 14+
• 拥有个人访问令牌的Airtable账户
• 您的Airtable Base ID

🚀 快速开始

步骤1：获取Airtable凭证

1. 个人访问令牌：访问Airtable账户 → 创建包含以下范围的令牌：

   • data.records:read - 从表读取记录
   • data.records:write - 创建、更新、删除记录
   • schema.bases:read - 查看表架构
   • schema.bases:write - v1.5.0新增 - 创建/修改表和字段
   • webhook:manage - (可选)用于webhook功能

2. Base ID：打开Airtable base并从URL复制ID：

   https://airtable.com/[BASE_ID]/...
   

步骤2：安装

选择以下安装方式之一：

🔷 TypeScript用户(开发推荐)

# 安装带TypeScript支持
npm install -g @rashidazarang/airtable-mcp

# 开发时安装类型
npm install --save-dev typescript @types/node

📦 JavaScript用户(生产就绪)

选项A：通过NPM安装(推荐)

npm install -g @rashidazarang/airtable-mcp

选项B：从GitHub克隆

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

步骤3：设置环境变量

在项目目录创建.env文件：

AIRTABLE_TOKEN=您的个人访问令牌
AIRTABLE_BASE_ID=您的base_id  # 可选 - 可使用list_bases工具发现

v3.2.5新增：AIRTABLE_BASE_ID现在为可选！您可以：

• 启动时不指定base ID，使用list_bases工具发现可访问的base
• 每次工具调用动态指定base ID
• 设置默认base方便使用(推荐)

安全提示：切勿将.env文件提交到版本控制！

步骤4：配置MCP客户端

🔷 TypeScript配置(增强开发者体验)

添加到Claude桌面版配置文件，使用TypeScript二进制：

MacOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\\Claude\\claude_desktop_config.json

{
  "mcpServers": {
    "airtable-typescript": {
      "command": "npx",
      "args": ["@rashidazarang/airtable-mcp"],
      "env": {
        "AIRTABLE_TOKEN": "您的Airtable令牌",
        "AIRTABLE_BASE_ID": "您的Base_ID",
        "NODE_ENV": "production",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

注意：AIRTABLE_BASE_ID可选。省略它可使用list_bases工具发现base。

📦 JavaScript配置(标准)

添加到Claude桌面版配置文件：

MacOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "airtable": {
      "command": "npx",
      "args": ["@rashidazarang/airtable-mcp"],
      "env": {
        "AIRTABLE_TOKEN": "您的Airtable令牌",
        "AIRTABLE_BASE_ID": "您的Base_ID"
      }
    }
  }
}

注意：AIRTABLE_BASE_ID可选。省略它可使用list_bases工具发现base。

无Base ID配置(新功能！)

启动时不指定base，动态发现：

{
  "mcpServers": {
    "airtable": {
      "command": "npx",
      "args": ["@rashidazarang/airtable-mcp"],
      "env": {
        "AIRTABLE_TOKEN": "您的Airtable令牌"
      }
    }
  }
}

然后使用list_bases工具发现可访问的base！

步骤5：重启MCP客户端

配置后，重启Claude桌面版或MCP客户端以加载Airtable服务器。

🎯 使用示例

配置完成后，您可以自然地与Airtable数据交互：

🔷 TypeScript开发

import { 
  AirtableMCPServer, 
  ListRecordsInput, 
  AnalyzeDataPrompt 
} from '@rashidazarang/airtable-mcp/types';

const server = new AirtableMCPServer();

// 类型安全数据操作
const params: ListRecordsInput = {
  table: '任务',
  maxRecords: 10,
  filterByFormula: "状态 = '活跃'"
};

const records = await server.handleToolCall('list_records', params);

// 类型安全AI分析
const analysis: AnalyzeDataPrompt = {
  table: '销售',
  analysis_type: 'predictive',
  confidence_level: 0.95
};

const insights = await server.handlePromptGet('analyze_data', analysis);

📦 自然语言交互

基本操作

"列出我所有可访问的Airtable base"
"显示项目表中的所有记录"
"创建优先级为'高'且截止日期为明天的新任务"
"将ID为rec123的任务状态更新为'已完成'"
"删除状态为'已归档'的所有记录"
"我的base中有哪些表？"
"搜索状态等于'活跃'的记录"

Webhook操作(v1.4.0+)

"为我的表创建webhook，通知https://my-app.com/webhook"
"列出base中所有活跃的webhook"
"显示最近的webhook负载"
"删除webhook ach123xyz"

架构管理(v1.5.0+)

"列出我所有可访问的Airtable base"
"显示此base的完整架构"
"描述项目表的所有字段详情"
"创建名为'任务'的新表，包含名称、优先级和截止日期字段"
"向现有项目表添加状态字段"
"Airtable中有哪些字段类型可用？"

批量操作与附件管理（v1.6.0+）

"在任务表中一次性创建5条新记录"
"批量更新多条记录的状态值"
"单次操作删除这3条记录"
"将图片URL附加到记录的photo字段"
"当前基地有哪些协作者？"
"显示本基地所有共享视图"

🛠️ 可用工具（总计33个）

📊 数据操作（7个工具）

工具	描述
list_tables	获取基地所有表结构信息
list_records	支持筛选和分页的记录查询
get_record	通过ID获取单条记录
create_record	向任意表添加新记录
update_record	修改现有记录字段
delete_record	从表中删除记录
search_records	支持Airtable公式的高级搜索

🪝 网络钩子管理（5个工具）

工具	描述
list_webhooks	查看基地配置的所有网络钩子
create_webhook	设置数据变更实时通知
delete_webhook	移除网络钩子配置
get_webhook_payloads	获取网络钩子通知历史
refresh_webhook	延长网络钩子有效期

🔍 结构探索（6个工具）- v1.5.0新增

工具	描述
list_bases	列出所有可访问的Airtable基地
get_base_schema	获取基地完整结构信息
describe_table	获取包含字段详情的表信息
list_field_types	所有Airtable字段类型参考指南
get_table_views	获取表视图配置信息

🏗️ 表管理（3个工具）- v1.5.0新增

工具	描述
create_table	创建带自定义字段的新表
update_table	修改表名和描述
delete_table	删除表（需安全确认）

🔧 字段管理（3个工具）- v1.5.0新增

工具	描述
create_field	添加支持所有类型的新字段
update_field	修改字段属性和选项
delete_field	删除字段（需安全确认）

⚡ 批量操作（4个工具）- v1.6.0新增

工具	描述
batch_create_records	单次最多创建10条记录
batch_update_records	同时更新最多10条记录
batch_delete_records	单次删除最多10条记录
batch_upsert_records	根据关键字段更新或创建记录

📎 附件管理（1个工具）- v1.6.0新增

工具	描述
upload_attachment	将公开URL文件附加到附件字段

👁️ 高级视图（2个工具）- v1.6.0新增

工具	描述
create_view	创建网格/表单/日历等自定义视图
get_view_metadata	获取视图筛选排序等元数据

🏢 基地管理（3个工具）- v1.6.0新增

工具	描述
create_base	创建带初始表结构的新基地
list_collaborators	查看协作者权限级别
list_shares	列出共享视图的公开配置

🤖 AI智能套件（10个提示）- v3.0.0新增

提示	描述	企业功能
analyze_data	含ML洞察的高级统计分析	置信区间/异常检测
create_report	智能报告生成与建议	多利益方定制/ROI分析
data_insights	商业智能与模式发现	跨表关联/预测指标
optimize_workflow	AI驱动的自动化建议	变更管理路线图
smart_schema_design	符合最佳实践的数据库优化	GDPR/HIPAA合规规划
data_quality_audit	全面数据质量评估	自动修复/治理框架
predictive_analytics	趋势预测功能	多算法支持
natural_language_query	智能处理自然语言提问	上下文感知
smart_data_transformation	AI辅助数据处理	质量规则/审计追踪
automation_recommendations	工作流优化建议	技术可行性分析

🔧 高级配置

Smithery云服务配置

云托管MCP服务器配置：

{
  "mcpServers": {
    "airtable": {
      "command": "npx",
      "args": [
        "@smithery/cli",
        "run",
        "@rashidazarang/airtable-mcp",
        "--token",
        "您的令牌",
        "--base",
        "您的基地ID"
      ]
    }
  }
}

直接Node.js执行

本地仓库运行时：

{
  "mcpServers": {
    "airtable": {
      "command": "node",
      "args": [
        "/路径/airtable-mcp/airtable_simple.js",
        "--token",
        "您的令牌",
        "--base",
        "您的基地ID"
      ]
    }
  }
}

🧪 测试指南

🔷 TypeScript测试

# 安装依赖
npm install

# 类型检查
npm run test:types

# 完整测试套件
npm run test:ts

# 构建并启动TS服务
npm run build
npm run start:ts

📦 JavaScript测试

# 设置环境变量
export AIRTABLE_TOKEN=您的令牌
export AIRTABLE_BASE_ID=您的基地ID

# 启动服务
node airtable_simple.js &

# 运行v1.6.0+完整测试
./test_v1.6.0_comprehensive.sh

TypeScript测试套件验证：

• 所有33个工具的类型安全
• 完整的CRUD操作
• 批量记录操作
• 100%测试覆盖率

🐛 故障排查

连接被拒

• 确认MCP服务运行中
• 检查8010端口未被占用
• 重启MCP客户端

令牌无效

• 核对个人访问令牌
• 确认令牌具有所需权限
• 检查凭证无多余空格

端口冲突解决方案

lsof -ti:8010 | xargs kill -9

📚 文档目录

🔷 TypeScript文档

• 📘 TS示例
• 🏗️ 类型定义
• 🧪 测试框架

📦 通用文档

• 🎆 v3.1.0版本说明
• 开发指南
• 安全通告

📦 版本历史

• v3.1.0 (2025-08-16) - 🔷 企业级TypeScript支持
• v3.0.0 (2025-08-16) - 🤖 革命性AI代理
• v1.6.0 (2025-08-15) - 🎆 批量操作与附件管理

🤝 贡献指南

欢迎提交PR，重大改动请先创建issue讨论。

📄 许可证

MIT 许可证 - 详情请参阅 LICENSE 文件

🙏 致谢

• 专为 Model Context Protocol 构建
• 基于 Airtable API 开发
• 兼容 Claude Desktop 及其他 MCP 客户端

📮 支持

• 问题反馈: GitHub Issues
• 讨论区: GitHub Discussions

---

版本: 3.2.4 | 状态: 🔷 TypeScript 已修复 + 🤖 AI 代理 | MCP 协议: 2024-11-05 完整版 | 类型安全: 企业级 | 智能程度: 10 个 AI 提示 | 安全性: 完全补丁 (XSS 已修复) | 最后更新: 2025年9月9日