Airtable OAuth MCP Server

A production-ready Model Context Protocol (MCP) server for Airtable with secure OAuth 2.0 authentication. This server enables AI assistants and applications to interact with Airtable bases through a standardized MCP interface, providing complete API coverage for all Airtable operations.

🚀 Features

Core Functionality

🔐 OAuth 2.0 Authentication - Secure token-based authentication with Airtable
📊 Complete Airtable API Coverage - 10 comprehensive MCP tools covering all operations
⚡ FastMCP Framework - Built on the high-performance FastMCP framework
☁️ Cloud-Ready - Production-ready deployment support
🔄 Dual Transport - Support for both STDIO and HTTP transport protocols

Security & Reliability

🔑 Environment-based Configuration - Secure credential management
✅ Type Safety - Full type hints and validation with Pydantic
🧪 Comprehensive Testing - Unit tests with pytest and coverage reporting
📝 Code Quality - Linting with Ruff and type checking with MyPy

Developer Experience

📚 Rich Documentation - Comprehensive setup and usage guides
🔧 Easy Setup - Simple installation with uv package manager
🎯 Typed Parameters - Clear, typed tool parameters for better IDE support
🔍 Flexible Querying - Advanced filtering, sorting, and search capabilities

📋 Prerequisites

Python 3.11+ - Latest Python version for optimal performance
uv - Fast Python package manager (install guide)
Airtable Developer Account - To create OAuth applications (sign up)

🚀 Quick Start

1. Installation

Clone the repository and install dependencies:

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

2. Airtable OAuth Setup

Create an Airtable OAuth Application:
- Visit Airtable Developer Hub
- Create a new OAuth integration
- Note your Client ID and Client Secret
- Set redirect URI to http://localhost:8000/oauth/callback

3. Environment Configuration

Copy the environment template and configure your credentials:

cp .env.example .env

Edit .env with your values:

# 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. Testing with MCP Inspector

Use the official MCP Inspector to test and interact with your server:

Start the server:
uv run python -m airtable_mcp http
Open MCP Inspector: Visit https://modelcontextprotocol.io/docs/tools/inspector
Connect to your server:
- Select "HTTP Streaming" transport
- Enter the URL: http://localhost:8000/mcp
- Click "Connect"
Authenticate with Airtable:
- The server will guide you through OAuth authentication
- Use the inspector to test available MCP tools

5. Run the Server

STDIO Transport (default):

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

HTTP Transport:

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

Additional Options:

# 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

The HTTP server will be available at http://localhost:8000/ (or custom host) with OAuth endpoints for web integration.

MCP Tools Available

The server provides 10 MCP tools for Airtable operations:

Base Operations:

list_bases() - List all accessible bases
list_tables(base_id, detail_level?) - List tables in a base
describe_table(base_id, table_id) - Get detailed table schema

Record Operations:

list_records(base_id, table_id, view?, filter_by_formula?, sort?, fields?) - List records with filtering
get_record(base_id, table_id, record_id) - Get a specific record
create_record(base_id, table_id, fields, typecast?) - Create a single record
create_records(base_id, table_id, records, typecast?) - Create multiple records
update_records(base_id, table_id, records, typecast?) - Update multiple records
delete_records(base_id, table_id, record_ids) - Delete multiple records
search_records(base_id, table_id, filter_by_formula, view?, fields?) - Search records with formulas

All tools now use typed parameters instead of generic args, making them more transparent to MCP clients.

Parameter Flexibility:

fields parameter accepts either a single field name (string) or array of field names
sort parameter expects array of objects: [{"field": "Name", "direction": "asc"}]

💡 Usage Examples

Basic Record Operations

# 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"]
})

Advanced Querying

# 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
})

Schema Discovery

# 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"
})

🛠️ Development

Getting Started

Fork and Clone:
git clone https://github.com/onimsha/airtable-mcp-server-oauth.git cd airtable-mcp-server-oauth
Setup Development Environment:
uv sync --all-extras
Run Tests:
uv run pytest uv run pytest --cov=src/airtable_mcp --cov-report=html

Code Quality

Type Checking:

uv run mypy src/

Linting:

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

Pre-commit Hooks:

pip install pre-commit
pre-commit install

Testing

The project includes comprehensive test coverage:

Unit Tests: Test individual components and functions
Integration Tests: Test OAuth flow and Airtable API interactions
Coverage Reports: Ensure >90% code coverage

# 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

Project Structure

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

⚙️ Configuration

All configuration is handled through environment variables (loaded from .env):

Required Variables

AIRTABLE_CLIENT_ID - OAuth client ID from Airtable
AIRTABLE_CLIENT_SECRET - OAuth client secret
AIRTABLE_REDIRECT_URI - OAuth callback URL

Optional Variables

HOST - Server host (default: 0.0.0.0)
PORT - Server port (default: 8000)
LOG_LEVEL - Logging level (default: INFO)
MCP_SERVER_NAME - Server name (optional)
MCP_SERVER_VERSION - Server version (optional)

🤝 Contributing

We welcome contributions! Please see our contribution guidelines:

Fork the repository and create a feature branch
Write tests for any new functionality
Ensure code quality with our linting and formatting tools
Update documentation for any API changes
Submit a pull request with a clear description

Contribution Areas

🐛 Bug fixes - Help us squash bugs
✨ New features - Add new Airtable API endpoints
📚 Documentation - Improve setup guides and examples
🧪 Testing - Increase test coverage
🚀 Performance - Optimize API calls and caching

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

FastMCP - Excellent MCP framework
Airtable - Powerful database platform
Model Context Protocol - Standard for AI tool integration

📚 Documentation

Additional Resources

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: Project Wiki

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

A production-ready Model Context Protocol server that enables AI assistants and applications to interact with Airtable bases through a standardized interface with secure OAuth 2.0 authentication.

Related MCP Servers

airtable-mcp-server
domdomegg
-
security
A
license
-
quality
A Model Context Protocol server that provides read and write access to Airtable databases. This server enables LLMs to inspect database schemas, then read and write records.
Last updated -
11
1,465
215
TypeScript
MIT License
Airtable MCP Server
felores
A
security
F
license
A
quality
A Model Context Protocol server that provides tools for programmatically managing Airtable bases, tables, fields, and records through Claude Desktop or other MCP clients.
Last updated -
12
105
19
JavaScript
MCP Toolkit
zxfgds
-
security
F
license
-
quality
A comprehensive Model Context Protocol server implementation that enables AI assistants to interact with file systems, databases, GitHub repositories, web resources, and system tools while maintaining security and control.
Last updated -
16
TypeScript
RL-MCP
rlefko
-
security
F
license
-
quality
A Model Context Protocol server that provides AI models with structured access to external data and services, acting as a bridge between AI assistants and applications, databases, and APIs in a standardized, secure way.
Last updated -
Python

View all related MCP servers

Airtable OAuth MCP Server