Skip to main content
Glama

Airtable OAuth MCP Server

by onimsha
GitHub
Python
MIT License
3
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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

  1. 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:

  1. Start the server:
    uv run python -m airtable_mcp http
  2. Open MCP Inspector: Visit https://modelcontextprotocol.io/docs/tools/inspector
  3. Connect to your server:
    • Select "HTTP Streaming" transport
    • Enter the URL: http://localhost:8000/mcp
    • Click "Connect"
  4. 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

  1. Fork and Clone:
    git clone https://github.com/onimsha/airtable-mcp-server-oauth.git cd airtable-mcp-server-oauth
  2. Setup Development Environment:
    uv sync --all-extras
  3. 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:

  1. Fork the repository and create a feature branch
  2. Write tests for any new functionality
  3. Ensure code quality with our linting and formatting tools
  4. Update documentation for any API changes
  5. 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

📚 Documentation

Additional Resources

📞 Support

Deploy Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

How are these scores calculated?

hybrid server

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

Tools

View all tools

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.

  1. 🚀 Features
    1. Core Functionality
    2. Security & Reliability
    3. Developer Experience
  2. 📋 Prerequisites
    1. 🚀 Quick Start
      1. 1. Installation
      2. 2. Airtable OAuth Setup
      3. 3. Environment Configuration
      4. 4. Testing with MCP Inspector
      5. 5. Run the Server
    2. MCP Tools Available
      1. 💡 Usage Examples
        1. Basic Record Operations
        2. Advanced Querying
        3. Schema Discovery
      2. 🛠️ Development
        1. Getting Started
        2. Code Quality
        3. Testing
        4. Project Structure
      3. ⚙️ Configuration
        1. Required Variables
        2. Optional Variables
      4. 🤝 Contributing
        1. Contribution Areas
      5. 📄 License
        1. 🙏 Acknowledgments
          1. 📚 Documentation
            1. Additional Resources
          2. 📞 Support

            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 -
              1,050
              265
              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 -
              416
              64
              • Apple

            • 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 -
              6
              1

            • 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 -
              2

            View all related MCP servers

            New MCP Servers

            MCP directory API

            We provide all the information about MCP servers via our MCP API.

            curl -X GET 'https://glama.ai/api/mcp/v1/servers/onimsha/airtable-mcp-server-oauth'

            If you have feedback or need assistance with the MCP directory API, please join our Discord server