Airtable集成服务

Airtable MCP 服务器

一个用于Airtable集成的全面模型上下文协议（MCP）服务器，提供工具以与Airtable数据库、表、记录和评论进行交互。

🚀 功能特性

可用工具

📋 先决条件

• Python 3.8 或更高版本
• 拥有API访问权限的Airtable账户
• 有效的Airtable API密钥

🛠️ 安装

1. 克隆仓库：

   复制

   git clone <repository-url>
   cd airtable-mcp
   

2. 安装依赖项：

   复制

   pip install -r requirements.txt
   

3. 设置环境变量：

   复制

   cp env.example .env
   

4. 配置您的 .env 文件：

   复制

   # Airtable API Configuration
   AIRTABLE_API_KEY=your_airtable_api_key_here
   
   # Optional: Base ID for testing (if you have an existing base)
   AIRTABLE_BASE_ID=your_base_id_here
   

获取您的Airtable API密钥

1. 首选 Airtable 账户
2. 导航至“个人访问令牌”
3. 点击“创建新令牌”
4. 为其命名并选择范围：
   • data.records:read
   • data.records:write
   • schema.bases:read
   • schema.bases:write
   • webhook:manage
5. 将生成的令牌复制到您的 .env 文件

🚀 使用方法

运行服务器

1. 启动MCP服务器：

   复制

   python airtable_mcp_server.py
   

2. 使用MCP Inspector：

   • 安装MCP Inspector： npm install -g @modelcontextprotocol/inspector
   • 运行： mcp-inspector
   • 配置您的 mcp-config.json：
   复制

   {
     "mcpServers": {
       "airtable": {
         "command": "python",
         "args": ["airtable_mcp_server.py"],
         "cwd": "D:/clg files/PROJECTS/airtable-mcp",
         "env": {
           "AIRTABLE_API_KEY": "your_airtable_api_key_here"
         }
       }
     }
   }
   

示例用法

创建一条记录

{
  "base_id": "appnJFyljOHYOYSji",
  "table_id_or_name": "Simple Table",
  "fields": "{\"Name\": \"New Task\", \"Status\": \"Pending\"}"
}

列出记录

{
  "base_id": "appnJFyljOHYOYSji",
  "table_id_or_name": "Simple Table",
  "max_records": 10
}

更新一条记录

{
  "base_id": "appnJFyljOHYOYSji",
  "table_id_or_name": "Simple Table",
  "record_id": "recXXXXXXXXXXXXXX",
  "fields": "{\"Status\": \"Completed\"}"
}

📚 工具文档

创建AIRTABLE数据库

⚠️（警告或注意的符号，无具体文字含义，可理解为“小心”或“注意”） 重要的这个工具仅验证配置并返回模拟响应。Airtable API不支持通过编程创建数据库。

参数：

• name (str): 基地名称
• tables (str): 包含表格配置的JSON字符串
• workspace_id (字符串): 工作区ID

示例：

{
  "name": "My Project Base",
  "tables": "[{\"name\": \"Tasks\", \"fields\": [{\"name\": \"Task Name\", \"type\": \"singleLineText\"}]}]",
  "workspace_id": "wspXXXXXXXXXXXXXX"
}

AIRTABLE_CREATE_RECORD 翻译为中文是：“在AIRTABLE中创建记录”

在表中创建一条新记录。

参数：

• base_id (字符串): 基本ID
• table_id_or_name (str): 表ID或名称
• fields (str): 包含字段值的JSON字符串

示例：

{
  "base_id": "appnJFyljOHYOYSji",
  "table_id_or_name": "Simple Table",
  "fields": "{\"Name\": \"New Task\", \"Status\": \"Pending\"}"
}

AIRTABLE列表记录

列出记录，并提供过滤和分页选项。

参数：

• base_id (str): 基本ID
• table_id_or_name (字符串): 表ID或名称
• max_records (int): 要返回的最大记录数（默认：0 = 无限制）
• filter_by_formula (字符串): 过滤公式
• sort (str): 包含排序配置的JSON字符串

示例：

{
  "base_id": "appnJFyljOHYOYSji",
  "table_id_or_name": "Simple Table",
  "max_records": 5,
  "filter_by_formula": "{Status} = 'Pending'"
}

🔧 配置

MCP 检查器配置

创建 mcp-config.json：

{
  "mcpServers": {
    "airtable": {
      "command": "python",
      "args": ["airtable_mcp_server.py"],
      "cwd": "D:/clg files/PROJECTS/airtable-mcp",
      "env": {
        "AIRTABLE_API_KEY": "your_airtable_api_key_here"
      }
    }
  }
}

环境变量

🚨 重要限制

AIRTABLE_CREATE_BASE 的限制

• 无法创建真实基础 Airtable API不支持此功能
• 返回模拟响应 - 仅验证配置
• 需要手动创建 - 使用Airtable网页界面

API 速率限制

• 每秒5个请求 每碱基（或每碱基对，根据上下文具体含义可能有所不同）
• 速率限制 自动处理
• 429错误 将尝试使用退避策略重新发送

记录限制

• 删除多条记录每次请求最多可获取10条记录
• 创建多条记录没有具体限制，但需考虑性能
• 列出记录支持分页功能 offset 参数

🛠️ 故障排除

常见问题

1. 认证错误

   复制

   Airtable API Error: AUTHENTICATION_REQUIRED
   

   • 检查你的 AIRTABLE_API_KEY 在 .env 文件
   • 验证API密钥是否具有正确的权限范围

2. 未找到基准

   复制

   Airtable API Error: INVALID_PERMISSIONS_OR_MODEL_NOT_FOUND
   

   • 验证基础ID是否正确
   • 检查你是否能访问基础（或：底座/数据库/基础系统等，具体含义需根据上下文确定）

3. 请求超时

   复制

   MCP error -32001: Request timed out
   

   • 检查你的网络连接
   • 验证Airtable API是否可访问

调试模式

通过设置环境变量启用调试日志记录：

export AIRTABLE_DEBUG=true

📝 字段类型参考