Airtable MCP Server Oauth

🚀 Airtable OAuth MCP Server

Airtable用のセキュアなOAuth 2.0認証を備えた、本番環境で使用可能なModel Context Protocol (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 Developer Hubにアクセスします。
   • 新しいOAuth統合を作成します。
   • Client IDとClient Secretをメモします。
   • リダイレクトURIをhttp://localhost:8000/oauth/callbackに設定します。

3. 環境設定

環境テンプレートをコピーし、資格情報を設定します。

cp .env.example .env

.envを編集し、値を入力します。

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

# Server Configuration
HOST="0.0.0.0"
PORT=8000
LOG_LEVEL="INFO"

4. MCP Inspectorを使用したテスト

公式のMCP Inspectorを使用して、サーバーをテストし、やり取りします。

1. サーバーを起動します。

   uv run python -m airtable_mcp http
   

2. MCP Inspectorを開きます。 https://modelcontextprotocol.io/docs/tools/inspectorにアクセスします。

3. サーバーに接続します。

   • "HTTP Streaming"トランスポートを選択します。
   • URLをhttp://localhost:8000/mcpと入力します。
   • "Connect"をクリックします。

4. Airtableで認証します。

   • サーバーがOAuth認証の手順を案内します。
   • Inspectorを使用して、利用可能なMCPツールをテストします。

5. サーバーを実行します。

STDIOトランスポート（デフォルト）

uv run python -m airtable_mcp
# or
uv run airtable-oauth-mcp

HTTPトランスポート

uv run python -m airtable_mcp http
# or with custom host/port
uv run python -m airtable_mcp http localhost 8001

追加オプション

# Set log level
uv run python -m airtable_mcp --log-level DEBUG

# Show help
uv run python -m airtable_mcp --help

# Show version
uv run python -m airtable_mcp --version

HTTPサーバーは、OAuthエンドポイントを備えたhttp://localhost:8000/（またはカスタムのホスト:ポート）で利用可能になり、Web統合が可能です。

✨ 主な機能

コア機能

• 🔐 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 Developer Account - OAuthアプリケーションを作成するためのアカウント (サインアップ)

💻 使用例

基本的な使用法

# List all records in a table
records = await client.call_tool("list_records", {
    "base_id": "appXXXXXXXXXXXXXX",
    "table_id": "tblYYYYYYYYYYYYYY"
})

# Create a new record
new_record = await client.call_tool("create_record", {
    "base_id": "appXXXXXXXXXXXXXX",
    "table_id": "tblYYYYYYYYYYYYYY",
    "fields": {
        "Name": "John Doe",
        "Email": "john@example.com",
        "Status": "Active"
    }
})

# Search records with filtering
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"]
})

高度な使用法

# List records with sorting and filtering
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 operations
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
})

スキーマの探索

# List all bases you have access to
bases = await client.call_tool("list_bases")

# Get detailed information about a specific table
table_info = await client.call_tool("describe_table", {
    "base_id": "appXXXXXXXXXXXXXX",
    "table_id": "tblYYYYYYYYYYYYYY"
})

# List all tables in a base
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%以上のコードカバレッジを確保します。

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=src/airtable_mcp

# Run specific test files
uv run pytest tests/test_oauth.py
uv run pytest tests/test_tools.py

プロジェクト構造

src/
├── airtable_mcp/           # Main MCP server package
│   ├── __init__.py         # Package initialization
│   ├── __main__.py         # Module entry point
│   ├── main.py             # CLI and application entry
│   ├── api/                # Airtable API client
│   │   ├── __init__.py
│   │   ├── client.py       # HTTP client for Airtable API
│   │   ├── exceptions.py   # API-specific exceptions
│   │   └── models.py       # Pydantic models for API responses
│   └── mcp/                # MCP server implementation
│       ├── __init__.py
│       ├── schemas.py      # MCP tool schemas
│       └── server.py       # FastMCP server with tools
└── mcp_oauth_lib/          # Reusable OAuth library
    ├── __init__.py         # Library initialization
    ├── auth/               # Authentication components
    │   ├── __init__.py
    │   ├── context.py      # Auth context management
    │   ├── middleware.py   # OAuth middleware
    │   └── utils.py        # Auth utilities
    ├── core/               # Core OAuth functionality
    │   ├── __init__.py
    │   ├── config.py       # OAuth configuration
    │   ├── flow.py         # OAuth flow implementation
    │   └── server.py       # OAuth server endpoints
    ├── providers/          # OAuth provider implementations
    │   ├── __init__.py
    │   ├── airtable.py     # Airtable OAuth provider
    │   └── base.py         # Base provider interface
    └── utils/              # OAuth utilities
        ├── __init__.py
        ├── pkce.py         # PKCE implementation
        └── state.py        # State management

設定

すべての設定は、環境変数（.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. プルリクエストを送信し、明確な説明を添えます。

コントリビューションの領域

• 🐛 バグ修正 - バグを解消するのを手伝ってください。
• ✨ 新機能 - 新しいAirtable APIエンドポイントを追加します。
• 📚 ドキュメント - セットアップガイドと例を改善します。
• 🧪 テスト - テストカバレッジを増やします。
• 🚀 パフォーマンス - API呼び出しとキャッシュを最適化します。

📄 ライセンス

このプロジェクトは、MITライセンスの下でライセンスされています。詳細については、LICENSEファイルを参照してください。

🙏 謝辞

• FastMCP - 優れたMCPフレームワーク
• Airtable - 強力なデータベースプラットフォーム
• Model Context Protocol - AIツール統合の標準

📞 サポート

• 問題報告: GitHub Issues
• ディスカッション: GitHub Discussions
• ドキュメント: Project Wiki