Airtable Mcp Server Oauth

Airtable Mcp Server Oauth

数据库 Python

🚀 Airtable OAuth MCP 服务器

Airtable OAuth MCP 服务器是一个具备安全 OAuth 2.0 认证的模型上下文协议 (MCP) 服务器，可用于生产环境。该服务器使 AI 助手和应用程序能够通过标准化的 MCP 接口与 Airtable 数据库进行交互，为所有 Airtable 操作提供完整的 API 覆盖。

🚀 快速开始

1. 安装

克隆仓库并安装依赖项：

git clone https://github.com/onimsha/airtable-mcp-server-oauth.git
cd airtable-mcp-server-oauth
uv sync

2. Airtable OAuth 设置

  1. 创建 Airtable OAuth 应用程序：
    • 访问 Airtable 开发者中心。
    • 创建一个新的 OAuth 集成。
    • 记录下 Client ID 和 Client Secret。
    • 将重定向 URI 设置为 http://localhost:8000/oauth/callback。

3. 环境配置

复制环境模板并配置凭证：

cp .env.example .env

编辑 .env 文件并填入相应的值：

# Airtable OAuth 配置
AIRTABLE_CLIENT_ID="your_airtable_client_id_here"
AIRTABLE_CLIENT_SECRET="your_airtable_client_secret_here"
AIRTABLE_REDIRECT_URI="http://localhost:8000/oauth/callback"

# 服务器配置
HOST="0.0.0.0"
PORT=8000
LOG_LEVEL="INFO"

4. 使用 MCP 检查器进行测试

使用官方 MCP 检查器来测试并与服务器进行交互：

  1. 启动服务器：
uv run python -m airtable_mcp http
  1. 打开 MCP 检查器： 访问 https://modelcontextprotocol.io/docs/tools/inspector。
  2. 连接到服务器：
    • 选择 "HTTP Streaming" 传输协议。
    • 输入 URL：http://localhost:8000/mcp。
    • 点击 "Connect"。
  3. 使用 Airtable 进行身份验证：
    • 服务器将引导你完成 OAuth 身份验证。
    • 使用检查器测试可用的 MCP 工具。

5. 运行服务器

STDIO 传输（默认）：

uv run python -m airtable_mcp
# 或者
uv run airtable-oauth-mcp

HTTP 传输：

uv run python -m airtable_mcp http
# 或者使用自定义主机/端口
uv run python -m airtable_mcp http localhost 8001

其他选项：

# 设置日志级别
uv run python -m airtable_mcp --log-level DEBUG

# 显示帮助信息
uv run python -m airtable_mcp --help

# 显示版本信息
uv run python -m airtable_mcp --version

HTTP 服务器将在 http://localhost:8000/（或自定义主机:端口）上可用，并带有用于 Web 集成的 OAuth 端点。

✨ 主要特性

核心功能

  • 🔐 OAuth 2.0 认证：与 Airtable 进行基于安全令牌的身份验证。
  • 📊 完整的 Airtable API 覆盖：10 个全面的 MCP 工具，涵盖所有操作。
  • ⚡ FastMCP 框架：基于高性能的 FastMCP 框架构建。
  • ☁️ 支持云部署：支持生产环境部署。
  • 🔄 双传输协议：支持 STDIO 和 HTTP 传输协议。

安全性和可靠性

  • 🔑 基于环境的配置：安全的凭证管理。
  • ✅ 类型安全：使用 Pydantic 提供完整的类型提示和验证。
  • 🧪 全面测试：使用 pytest 进行单元测试并提供覆盖率报告。
  • 📝 代码质量：使用 Ruff 进行代码检查，使用 MyPy 进行类型检查。

开发者体验

  • 📚 丰富的文档：提供全面的设置和使用指南。
  • 🔧 易于设置：使用 uv 包管理器进行简单安装。
  • 🎯 类型化参数：清晰的类型化工具参数，提供更好的 IDE 支持。
  • 🔍 灵活查询：具备高级过滤、排序和搜索功能。

📦 安装指南

前提条件

  • Python 3.11+：使用最新的 Python 版本以获得最佳性能。
  • uv：快速 Python 包管理器（安装指南）。
  • Airtable 开发者账户：用于创建 OAuth 应用程序（注册）。

💻 使用示例

基础用法

# 列出表中的所有记录
records = await client.call_tool("list_records", {
"base_id": "appXXXXXXXXXXXXXX",
"table_id": "tblYYYYYYYYYYYYYY"
})

# 创建一条新记录
new_record = await client.call_tool("create_record", {
"base_id": "appXXXXXXXXXXXXXX",
"table_id": "tblYYYYYYYYYYYYYY",
"fields": {
"Name": "John Doe",
"Email": "john@example.com",
"Status": "Active"
}
})

# 过滤搜索记录
filtered_records = await client.call_tool("search_records", {
"base_id": "appXXXXXXXXXXXXXX",
"table_id": "tblYYYYYYYYYYYYYY",
"filter_by_formula": "AND({Status} = 'Active', {Email} != '')",
"fields": ["Name", "Email", "Status"]
})

高级用法

# 带排序和过滤条件列出记录
records = await client.call_tool("list_records", {
"base_id": "appXXXXXXXXXXXXXX",
"table_id": "tblYYYYYYYYYYYYYY",
"view": "Grid view",
"filter_by_formula": "{Priority} = 'High'",
"sort": [
{"field": "Created", "direction": "desc"},
{"field": "Name", "direction": "asc"}
],
"fields": ["Name", "Priority", "Created", "Status"]
})

# 批量操作
batch_create = await client.call_tool("create_records", {
"base_id": "appXXXXXXXXXXXXXX",
"table_id": "tblYYYYYYYYYYYYYY",
"records": [
{"fields": {"Name": "Record 1", "Value": 100}},
{"fields": {"Name": "Record 2", "Value": 200}},
{"fields": {"Name": "Record 3", "Value": 300}}
],
"typecast": True
})

模式发现

# 列出所有可访问的数据库
bases = await client.call_tool("list_bases")

# 获取特定表的详细信息
table_info = await client.call_tool("describe_table", {
"base_id": "appXXXXXXXXXXXXXX",
"table_id": "tblYYYYYYYYYYYYYY"
})

# 列出数据库中的所有表
tables = await client.call_tool("list_tables", {
"base_id": "appXXXXXXXXXXXXXX",
"detail_level": "full"
})

📚 详细文档

可用的 MCP 工具

服务器为 Airtable 操作提供了 10 个 MCP 工具：

数据库操作：

  • list_bases() - 列出所有可访问的数据库。
  • list_tables(base_id, detail_level?) - 列出数据库中的表。
  • describe_table(base_id, table_id) - 获取表的详细模式。

记录操作：

  • list_records(base_id, table_id, view?, filter_by_formula?, sort?, fields?) - 带过滤条件列出记录。
  • get_record(base_id, table_id, record_id) - 获取特定记录。
  • create_record(base_id, table_id, fields, typecast?) - 创建单条记录。
  • create_records(base_id, table_id, records, typecast?) - 创建多条记录。
  • update_records(base_id, table_id, records, typecast?) - 更新多条记录。
  • delete_records(base_id, table_id, record_ids) - 删除多条记录。
  • search_records(base_id, table_id, filter_by_formula, view?, fields?) - 使用公式搜索记录。

所有工具现在使用类型化参数而非通用的 args，这使得它们对 MCP 客户端更加透明。

参数灵活性：

  • fields 参数可以接受单个字段名（字符串）或字段名数组。
  • sort 参数期望一个对象数组：[{"field": "Name", "direction": "asc"}]。

其他资源

🔧 技术细节

开发入门

  1. 分叉并克隆仓库：
git clone https://github.com/onimsha/airtable-mcp-server-oauth.git
cd airtable-mcp-server-oauth
  1. 设置开发环境：
uv sync --all-extras
  1. 运行测试：
uv run pytest
uv run pytest --cov=src/airtable_mcp --cov-report=html

代码质量

类型检查：

uv run mypy src/

代码检查：

uv run ruff check src/
uv run ruff format src/

预提交钩子：

pip install pre-commit
pre-commit install

测试

项目包含全面的测试覆盖：

  • 单元测试：测试单个组件和函数。
  • 集成测试：测试 OAuth 流程和 Airtable API 交互。
  • 覆盖率报告：确保代码覆盖率 >90%。
# 运行所有测试
uv run pytest

# 运行带覆盖率的测试
uv run pytest --cov=src/airtable_mcp

# 运行特定的测试文件
uv run pytest tests/test_oauth.py
uv run pytest tests/test_tools.py

项目结构

src/
├── airtable_mcp/           # 主要的 MCP 服务器包
│   ├── __init__.py         # 包初始化
│   ├── __main__.py         # 模块入口点
│   ├── main.py             # CLI 和应用程序入口
│   ├── api/                # Airtable API 客户端
│   │   ├── __init__.py
│   │   ├── client.py       # Airtable API 的 HTTP 客户端
│   │   ├── exceptions.py   # API 特定的异常
│   │   └── models.py       # API 响应的 Pydantic 模型
│   └── mcp/                # MCP 服务器实现
│       ├── __init__.py
│       ├── schemas.py      # MCP 工具模式
│       └── server.py       # 带有工具的 FastMCP 服务器
└── mcp_oauth_lib/          # 可重用的 OAuth 库
├── __init__.py         # 库初始化
├── auth/               # 认证组件
│   ├── __init__.py
│   ├── context.py      # 认证上下文管理
│   ├── middleware.py   # OAuth 中间件
│   └── utils.py        # 认证实用工具
├── core/               # 核心 OAuth 功能
│   ├── __init__.py
│   ├── config.py       # OAuth 配置
│   ├── flow.py         # OAuth 流程实现
│   └── server.py       # OAuth 服务器端点
├── providers/          # OAuth 提供商实现
│   ├── __init__.py
│   ├── airtable.py     # Airtable OAuth 提供商
│   └── base.py         # 基础提供商接口
└── utils/              # OAuth 实用工具
├── __init__.py
├── pkce.py         # PKCE 实现
└── state.py        # 状态管理

配置

所有配置通过环境变量（从 .env 文件加载）进行处理：

必需变量

  • AIRTABLE_CLIENT_ID - 来自 Airtable 的 OAuth 客户端 ID。
  • AIRTABLE_CLIENT_SECRET - OAuth 客户端密钥。
  • AIRTABLE_REDIRECT_URI - OAuth 回调 URL。

可选变量

  • HOST - 服务器主机（默认：0.0.0.0）。
  • PORT - 服务器端口（默认：8000）。
  • LOG_LEVEL - 日志级别（默认：INFO）。
  • MCP_SERVER_NAME - 服务器名称（可选）。
  • MCP_SERVER_VERSION - 服务器版本（可选）。

🤝 贡献指南

我们欢迎贡献！请遵循以下贡献指南：

  1. 分叉仓库并创建一个功能分支。
  2. 编写测试：为任何新功能编写测试。
  3. 确保代码质量：使用我们的代码检查和格式化工具。
  4. 更新文档：为任何 API 更改更新文档。
  5. 提交拉取请求：并提供清晰的描述。

贡献领域

  • 🐛 修复 bug：帮助我们解决问题。
  • ✨ 新功能：添加新的 Airtable API 端点。
  • 📚 文档：改进设置指南和示例。
  • 🧪 测试：提高测试覆盖率。
  • 🚀 性能：优化 API 调用和缓存。

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

🙏 致谢

📞 支持

默认排序 时间排序

0 个评论

« 上一篇
Bitable Mcp
下一篇 »
Cursor DB Explorer
  • 0 关注
  • 0 收藏，10 浏览
  • system 提出于 2025-09-23 22:00

相似服务问题

相关AI产品

  • 暂无相关AI产品

热议话题 »