README.md•7.53 kB
# Airtable MCP Server
A Model Context Protocol (MCP) server for Airtable, designed to integrate with AI-powered applications and n8n workflows. This server provides a standardized interface for interacting with Airtable bases, tables, and records.
## 🚀 Features
- **16 Core Tools**: Complete CRUD operations for Airtable
- **Batch Operations**: Create, update, and delete multiple records at once
- **Schema Management**: Access table, field, and view information
- **HTTP Streamable**: Compatible with n8n and other HTTP-based MCP clients
- **TypeScript**: Full type safety and modern JavaScript features
- **Render Ready**: Pre-configured for deployment on Render
## 🛠️ Available Tools
### Base Operations
- `get_base_info` - Get information about the Airtable base
- `list_tables` - List all tables in the base
### Table Operations
- `get_table_info` - Get detailed table information
- `list_fields` - List all fields in a table
- `get_field_info` - Get detailed field information
### Record Operations
- `list_records` - List records with filtering, sorting, and pagination
- `get_record` - Get a specific record by ID
- `create_record` - Create a new record
- `update_record` - Update an existing record
- `delete_record` - Delete a record
### Batch Operations
- `create_records` - Create multiple records (up to 10)
- `update_records` - Update multiple records (up to 10)
- `delete_records` - Delete multiple records (up to 10)
### View Operations
- `list_views` - List all views for a table
- `get_view_info` - Get detailed view information
## 🚀 Quick Start
### Prerequisites
- Node.js 20+
- Airtable API key
- Airtable base ID
### Installation
1. **Clone the repository**
```bash
git clone https://github.com/jjwjr94/airtable-mcp.git
cd airtable-mcp
```
2. **Install dependencies**
```bash
npm install
```
3. **Set up environment variables**
```bash
cp env.example .env
# Edit .env with your Airtable credentials
```
4. **Start the development server**
```bash
npm run dev:http
```
### Environment Variables
```bash
# Server Configuration
NODE_ENV=development
PORT=3000
# Airtable Configuration
AIRTABLE_API_KEY=your_airtable_api_key_here
AIRTABLE_BASE_ID=your_base_id_here
```
## 🔧 Usage
### HTTP Server (Recommended for n8n)
The HTTP server runs on port 3000 by default and provides these endpoints:
- **Health Check**: `GET /health`
- **MCP Endpoint**: `POST /mcp`
- **Set Credentials**: `POST /set-credentials`
### Headers Required
For all MCP requests, include these headers:
```
x-airtable-api-key: YOUR_API_KEY
x-airtable-base-id: YOUR_BASE_ID
```
### Example MCP Request
```bash
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-H "x-airtable-api-key: YOUR_API_KEY" \
-H "x-airtable-base-id: YOUR_BASE_ID" \
-d '{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "list_tables",
"arguments": {}
},
"id": "1"
}'
```
## 🚀 Deployment
### Render (Recommended)
1. **Fork this repository**
2. **Connect to Render**
3. **Deploy as a Web Service**
4. **Set environment variables in Render dashboard**
The `render.yaml` file is pre-configured for easy deployment.
### Environment Variables for Production
```bash
NODE_ENV=production
PORT=10000
```
## 🧪 Testing
### Run Tests
```bash
# Start the server first
npm run dev:http
# In another terminal, run tests
npm test
```
### Test Individual Endpoints
```bash
# Health check
curl http://localhost:3000/health
# List tools
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-H "x-airtable-api-key: YOUR_API_KEY" \
-H "x-airtable-base-id: YOUR_BASE_ID" \
-d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":"1"}'
```
## 🔌 n8n Integration
### HTTP Request Node Configuration
1. **Method**: POST
2. **URL**: `https://your-render-app.onrender.com/mcp`
3. **Headers**:
- `Content-Type: application/json`
- `x-airtable-api-key: {{ $json.apiKey }}`
- `x-airtable-base-id: {{ $json.baseId }}`
4. **Body**:
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "list_tables",
"arguments": {}
},
"id": "{{ $json.requestId }}"
}
```
### Example n8n Workflow
1. **Set** node to configure Airtable credentials
2. **HTTP Request** node to call MCP tools
3. **Switch** node to handle different tool responses
4. **Process** node to format data for your needs
## 📚 API Reference
### Tool: list_records
List records from a table with optional filtering and pagination.
**Parameters:**
- `tableId` (required): The ID of the table
- `pageSize` (optional): Number of records to return (max 100)
- `filterByFormula` (optional): Airtable formula to filter records
- `sort` (optional): Sorting configuration
- `fields` (optional): Specific fields to return
- `view` (optional): View ID to use
**Example:**
```json
{
"name": "list_records",
"arguments": {
"tableId": "tblXXXXXXXXXXXXXX",
"pageSize": 50,
"filterByFormula": "{Status} = 'Active'",
"sort": [{"field": "Name", "direction": "asc"}],
"fields": ["Name", "Status", "Created"]
}
}
```
### Tool: create_record
Create a new record in a table.
**Parameters:**
- `tableId` (required): The ID of the table
- `fields` (required): The field values for the new record
**Example:**
```json
{
"name": "create_record",
"arguments": {
"tableId": "tblXXXXXXXXXXXXXX",
"fields": {
"Name": "New Project",
"Status": "Active",
"Priority": "High"
}
}
}
```
## 🔒 Security
- **CORS**: Configured for Render and n8n domains
- **Helmet**: Security headers enabled
- **Input Validation**: All inputs are validated
- **Error Handling**: Secure error messages
## 🚀 Development
### Scripts
```bash
npm run build # Build TypeScript
npm run start # Start production server
npm run start:http # Start HTTP server
npm run dev # Development mode
npm run dev:http # HTTP development mode
npm run watch # Watch mode for TypeScript
npm test # Run tests
npm run inspector # MCP inspector
```
### Project Structure
```
airtable-mcp/
├── src/
│ ├── airtable-client-wrapper.ts # Airtable API client
│ ├── tool-handler.ts # MCP tool definitions
│ └── version.ts # Version information
├── index.ts # Standard MCP server
├── index-http.ts # HTTP server
├── test-http-server.js # Test suite
├── render.yaml # Render deployment config
└── package.json # Dependencies and scripts
```
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
## 📄 License
MIT License - see [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- Built for the Model Context Protocol
- Powered by Airtable API
- Compatible with Claude Desktop and other MCP clients
- Designed for n8n integration
## 📞 Support
- **Issues**: [GitHub Issues](https://github.com/jjwjr94/airtable-mcp/issues)
- **Discussions**: [GitHub Discussions](https://github.com/jjwjr94/airtable-mcp/discussions)
---
**Version**: 1.0.0 | **Status**: 🚀 Production Ready | **MCP Protocol**: 2025-06-18 | **Type Safety**: Full TypeScript | **Last Updated**: January 2025