Airtable MCP Server Oauth

🚀 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

2. 打開 MCP 檢查器： 訪問 https://modelcontextprotocol.io/docs/tools/inspector。
3. 連接到服務器：
   • 選擇 "HTTP Streaming" 傳輸協議。
   • 輸入 URL：http://localhost:8000/mcp。
   • 點擊 "Connect"。
4. 使用 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"}]。

其他資源

• OAuth2 流程文檔
• 動態客戶端註冊
• Airtable API 參考
• MCP 規範

🔧 技術細節

開發入門

1. 分叉並克隆倉庫：

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

2. 設置開發環境：

uv sync --all-extras

3. 運行測試：

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 文件。

🙏 致謝

• FastMCP：優秀的 MCP 框架。
• Airtable：強大的數據庫平臺。
• 模型上下文協議：AI 工具集成標準。

📞 支持

• 問題反饋：GitHub 問題
• 討論交流：GitHub 討論
• 項目文檔：項目維基