Airtable MCP Server

An MCP (Model Context Protocol) server that enables AI models to interact with Airtable databases. This server provides a bridge between Large Language Models (LLMs) and Airtable, allowing for operations like creating records, listing tables, and searching data.

Features

• 🔍 Base & Table Management

  • List accessible bases
  • Browse tables within bases
  • View table schemas

• 📝 Record Operations

  • Create new records
  • List existing records
  • Search records using Airtable formulas
  • Filter and paginate results

• 🔐 Security

  • Secure API key management
  • Rate limiting protection
  • Input validation
  • Error handling

• 🛠 Developer Features

  • TypeScript support
  • Comprehensive testing suite
  • Detailed logging
  • Easy configuration

Prerequisites

• Node.js (v16 or higher)
• npm or yarn
• Airtable account and API key

Installation

1. Clone the repository

git clone https://github.com/your-username/airtable-mcp-server.git
cd airtable-mcp-server

2. Install dependencies

npm install

3. Configure environment variables

cp .env.example .env

Edit .env with your Airtable API key and other configuration options.

4. Build the server

npm run build

Configuration

Environment Variables

Variable	Description	Required	Default
AIRTABLE_API_KEY	Your Airtable API key	Yes	-
DEBUG	Enable debug logging	No	false
MAX_RECORDS_PER_REQUEST	Maximum records per request	No	100
REQUEST_TIMEOUT	API request timeout (ms)	No	30000
RATE_LIMIT	Requests per minute	No	5

Airtable API Key Setup

1. Log in to your Airtable account
2. Go to your account page
3. Under the API section:
   • Generate a new API key or use an existing one
   • Copy the API key
4. Add the key to your .env file

Usage

Starting the Server

npm start

Integration with Claude Desktop

1. Open your Claude Desktop configuration:

   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

2. Add the server configuration:

{
  "mcpServers": {
    "airtable": {
      "command": "node",
      "args": ["/path/to/airtable-mcp-server/dist/index.js"],
      "env": {
        "AIRTABLE_API_KEY": "your_api_key_here"
      }
    }
  }
}

3. Restart Claude Desktop

Available Tools

create-record

Creates a new record in an Airtable table.

{
  baseId: string;    // Airtable base ID
  tableId: string;   // Table ID or name
  fields: object;    // Record fields
}

list-records

Lists records from a table.

{
  baseId: string;     // Airtable base ID
  tableId: string;    // Table ID or name
  maxRecords?: number; // Maximum records to return
  view?: string;      // Optional view name
}

search-records

Searches records using Airtable formula.

{
  baseId: string;      // Airtable base ID
  tableId: string;     // Table ID or name
  filterFormula: string; // Search formula
}

Available Resources

• airtable://bases - List accessible bases
• airtable://bases/{baseId}/tables - List tables in a base
• airtable://bases/{baseId}/tables/{tableId}/schema - Get table schema

Development

Project Structure

airtable-mcp-server/
├── src/
│   ├── index.ts           # Entry point
│   ├── server.ts          # MCP server implementation
│   ├── airtable/
│   │   ├── client.ts      # Airtable client wrapper
│   │   └── types.ts       # TypeScript types
│   └── utils/
│       ├── error-handler.ts
│       └── validators.ts
├── test/
│   ├── integration.test.ts
│   ├── server.test.ts
│   └── airtable.test.ts
└── dist/                  # Compiled JavaScript

Running Tests

# Run all tests
npm test

# Run with coverage
npm test -- --coverage

# Run integration tests
npm test -- integration.test.ts

Building

# Build once
npm run build

# Build in watch mode
npm run dev

Error Handling

The server implements comprehensive error handling:

• Input validation errors
• API rate limiting
• Network timeouts
• Authentication failures
• Resource not found errors

Security Considerations

1. API Key Protection
   • Never commit API keys to version control
   • Use environment variables
   • Rotate keys regularly
2. Rate Limiting
   • Configurable rate limits
   • Protection against abuse
3. Input Validation
   • All inputs are validated
   • Protection against injection

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

Testing

Unit Tests

npm test

Integration Tests

# Setup test environment
cp .env.example .env.test
# Edit .env.test with test credentials
npm test -- integration.test.ts

Troubleshooting

Common Issues

1. Connection Errors

   • Check API key validity
   • Verify network connection
   • Check rate limiting

2. Permission Errors

   • Verify base access permissions
   • Check API key scopes

3. Rate Limiting

   • Adjust RATE_LIMIT in .env
   • Implement request queuing
   • Add delay between requests

License

MIT

Support

For issues and feature requests, please open an issue.

Acknowledgments

• Model Context Protocol (MCP) team
• Airtable API team
• Contributors and maintainers