AI导哈

Airtable记录检索服务器

一个用于Airtable集成的模型上下文协议（MCP）服务器，允许AI助手从Airtable基础中检索记录。

  • by jak-myers
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 jakreymyers/airtable-mcp-server

使用说明

Airtable MCP服务器

用于Airtable集成的模型上下文协议（MCP）服务器，允许AI助手从Airtable库中检索记录。

🚀 快速开始

先决条件

  • Node.js 18+
  • Airtable 个人访问令牌
  • 带无障碍桌子的Airtable基座

安装

  1. 克隆并设置项目：

    git clone <repository-url>
cd airtable-mcp-server
npm install

  2. 获取您的Airtable个人访问令牌：

    • 访问https://airtable.com/create/tokens
    • 为目标库创建具有读取权限的新令牌
    • 复制令牌（格式： patXXXXXXXXXXXXXX.xxxxxxxxxx...)

  3. 配置环境：

    cp .env.example .env
# Edit .env and set your AIRTABLE_PERSONAL_ACCESS_TOKEN

  4. 构建和测试：

    npm run build
npm start

🔧 用法

服务器提供了一个工具： getAirtableRecord

刀具参数

参数 类型 必填 说明
recordId string Yes Airtable记录ID（格式： recXXXXXXXXXXXXXX)
baseId string 是 Airtable基ID（格式： appXXXXXXXXXXXXXX)
tableName string Yes 包含记录的表的名称

示例用法

输入：

{
  "recordId": "recABC123DEF456",
  "baseId": "appXYZ789ABC123",
  "tableName": "Artists"
}

输出：

{
  "content": [
    {
      "type": "text",
      "text": "{\"id\":\"recABC123DEF456\",\"fields\":{\"Name\":\"Vincent van Gogh\",\"Bio\":\"Dutch painter...\",\"Genre\":[\"Post-Impressionism\"]},\"createdTime\":\"2024-01-15T10:30:00.000Z\"}"
    }
  ]
}

🔗 MCP客户端集成

克劳德桌面

添加到您的 ~/.claude/mcp.json （参见 examples/claude-desktop.json):

{
  "mcpServers": {
    "airtable": {
      "command": "node",
      "args": ["/path/to/airtable-mcp-server/dist/index.js"],
      "env": {
        "AIRTABLE_PERSONAL_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

光标IDE

添加到您的 .cursor/mcp.json （参见 examples/cursor-ide.json):

{
  "mcpServers": {
    "airtable": {
      "command": "node",
      "args": ["./dist/index.js"],
      "env": {
        "AIRTABLE_PERSONAL_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

VS代码

添加到MCP配置中（请参阅 examples/vscode.json):

{
  "mcpServers": {
    "airtable": {
      "command": "node",
      "args": ["./dist/index.js"],
      "env": {
        "AIRTABLE_PERSONAL_ACCESS_TOKEN": "your_token_here"
      },
      "transport": "stdio"
    }
  }
}

全球安装（NPM）

npm install -g airtable-mcp-server

# Then in your MCP client config:
{
  "command": "npx",
  "args": ["-y", "airtable-mcp-server@latest"]
}

🛠️ 发展

脚本

命令 描述
npm run dev 热装开发模式
npm run build 将TypeScript编译为JavaScript
npm start 运行已编译的服务器
npm run clean 删除构建工件
npm test 运行单元测试
npm run test:integration 运行集成测试
npm run test:all 运行所有测试

项目结构

airtable-mcp-server/
├── src/
│   ├── index.ts              # Server entry point
│   ├── config/
│   │   ├── index.ts          # Configuration management
│   │   └── validation.ts     # Config validation
│   ├── tools/
│   │   ├── index.ts          # Tool registry
│   │   └── getRecord.ts      # Record retrieval tool
│   ├── types/
│   │   └── index.ts          # Type definitions
│   └── utils/
│       ├── error.ts          # Error handling
│       └── validation.ts     # Input validation
├── tests/
│   ├── integration.test.ts   # Integration tests
│   ├── unit/
│   │   └── tools.test.ts     # Unit tests
│   └── fixtures/
│       └── sample-record.json # Test data
├── examples/
│   ├── claude-desktop.json   # Claude Desktop config
│   ├── cursor-ide.json       # Cursor IDE config
│   ├── vscode.json           # VS Code config
│   └── usage.md              # Usage examples
├── docs/
│   └── DEPLOYMENT.md         # Deployment guide
├── dist/                     # Compiled JavaScript (generated)
├── PRD.md                    # Product requirements
├── CLAUDE.md                 # Claude Code guidance
├── package.json
├── tsconfig.json
├── .env.example
└── README.md

🔒 安全

许可证管理

  • 仅限环境：从不将令牌提交到版本控制
  • 最小范围：仅对目标库使用只读权限
  • 代币轮换：支持在需要时刷新令牌

输入验证

  • 记录ID必须与模式匹配： rec[A-Za-z0-9]{14}
  • 基本ID必须与模式匹配： app[A-Za-z0-9]{14}
  • 表名经过消毒，以确保安全使用

速率限制

  • 尊重Airtable的5个请求/秒/基本限制
  • 对速率限制错误实施指数回退
  • 可配置的重试尝试和延迟

⚙️ 配置

环境变量：

变量 必填 默认 描述
AIRTABLE_PERSONAL_ACCESS_TOKEN 是 - 您的Airtable PAT
AIRTABLE_TIMEOUT 否 30000 请求超时（毫秒）
AIRTABLE_RETRY_ATTEMPTS 否 3 重试次数
AIRTABLE_RETRY_DELAY 否 1000 重试延迟（毫秒）

🚨 错误处理

服务器处理各种错误情况：

错误类型 HTTP状态 描述
记录ID无效 404 找不到记录或格式无效
身份验证失败 401 令牌无效或过期
禁止访问 403 令牌缺少权限
超出速率限制 429 请求太多
无效参数 422 请求数据格式错误
服务器错误 500+ Airtable服务问题

所有错误都会返回带有有用消息的结构化响应。

📊 演出

满足要求

  • ✅ 响应时间：记录检索时间<2秒
  • ✅ 内存使用：<50MB基线占用空间
  • ✅ 并发请求：最多可处理Airtable的速率限制
  • ✅ 错误恢复：优雅的操控，指数级回退

监控

  • 请求/响应日志记录到stderr
  • 启动时的配置验证
  • 用于调试的结构化错误消息

🧪 测试

手动测试

  1. 有效记录检索：

    # Replace with your actual IDs
echo '{"recordId":"recYourRecordId","baseId":"appYourBaseId","tableName":"YourTable"}' | node dist/index.js

  2. 错误场景：

    • 记录ID格式无效
    • 不存在记录
    • 无效的基本ID
    • 缺少权限
    • 速率限制

测试用例

该实施包括对以下内容的全面错误处理：

  • ✅ 成功检索记录
  • ✅ 验证错误（ID格式无效）
  • ✅ 身份验证失败（401/403）
  • ✅ 未发现错误（404）
  • ✅ 速率限制（429）
  • ✅ 服务器错误（500+）

🔄 未来的增强功能

计划的功能

  • 其他工具：创建、更新、删除操作
  • 批量操作：多记录处理
  • 高级查询：基于公式的过滤
  • 字段选择：粒度字段检索
  • HTTP传输：REST API支持
  • 缓存：基于Redis的响应缓存

生产特点

  • OAuth集成
  • 多基地支持
  • 审核日志记录
  • 高可用性部署

🆘 故障排除

常见问题

服务器无法启动：

  • 检查一下 AIRTABLE_PERSONAL_ACCESS_TOKEN 已设置
  • 验证令牌是否具有目标库的读取权限
  • 确保已安装Node.js 18+

身份验证错误：

  • 验证令牌是否有效且未过期
  • 检查令牌是否可以访问指定的基
  • 确认基本ID格式： appXXXXXXXXXXXXXX

未找到记录：

  • 验证记录ID格式： recXXXXXXXXXXXXXX
  • 检查指定表中是否存在记录
  • 确认表名完全正确（区分大小写）

速率限制：

  • 降低请求频率
  • 实现请求之间的延迟
  • 监视Airtable使用限制

调试模式

启用详细日志记录：

DEBUG=* npm run dev

📄 许可证

MIT许可证-有关详细信息，请参阅许可证文件。

🤝 贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 进行更改
  4. 添加新功能的测试
  5. 提交拉取请求

📚 资源

版本: 1.0.0
兼容：克劳德桌面，光标IDE，VS代码MCP扩展
Node.js：需要18+
空气表API：个人访问令牌身份验证

相关 MCP