Enables interaction with Airtable bases through OAuth 2.0 authentication, providing complete API coverage for all Airtable operations including listing bases, managing tables, and performing record operations (creating, reading, updating, deleting, searching, and filtering records).
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:
2. Airtable OAuth Setup
Create an Airtable OAuth Application:
Visit Airtable Developer Hub
Create a new OAuth integration
Note your
Client ID
andClient Secret
Set redirect URI to
http://localhost:8000/oauth/callback
3. Environment Configuration
Copy the environment template and configure your credentials:
Edit .env
with your values:
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 httpOpen 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):
HTTP Transport:
Additional Options:
The HTTP server will be available at http://localhost:8000/
(or custom host:port) 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 baseslist_tables(base_id, detail_level?)
- List tables in a basedescribe_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 filteringget_record(base_id, table_id, record_id)
- Get a specific recordcreate_record(base_id, table_id, fields, typecast?)
- Create a single recordcreate_records(base_id, table_id, records, typecast?)
- Create multiple recordsupdate_records(base_id, table_id, records, typecast?)
- Update multiple recordsdelete_records(base_id, table_id, record_ids)
- Delete multiple recordssearch_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 namessort
parameter expects array of objects:[{"field": "Name", "direction": "asc"}]
💡 Usage Examples
Basic Record Operations
Advanced Querying
Schema Discovery
🛠️ Development
Getting Started
Fork and Clone:
git clone https://github.com/onimsha/airtable-mcp-server-oauth.git cd airtable-mcp-server-oauthSetup Development Environment:
uv sync --all-extrasRun Tests:
uv run pytest uv run pytest --cov=src/airtable_mcp --cov-report=html
Code Quality
Type Checking:
Linting:
Pre-commit Hooks:
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
Project Structure
⚙️ Configuration
All configuration is handled through environment variables (loaded from .env
):
Required Variables
AIRTABLE_CLIENT_ID
- OAuth client ID from AirtableAIRTABLE_CLIENT_SECRET
- OAuth client secretAIRTABLE_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
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
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.
Related MCP Servers
- -securityAlicense-qualityA 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 -2,555305TypeScriptMIT License
- AsecurityFlicenseAqualityA 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 -32166
- -securityFlicense-qualityA 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 -331