Airtable MCP Server

A Model Context Protocol (MCP) server for Airtable integration that allows AI assistants to retrieve records from Airtable bases.

🚀 Quick Start

Prerequisites

• Node.js 18+

• Airtable Personal Access Token

• Airtable base with accessible tables

Installation

1. Clone and setup the project:

   git clone <repository-url>
   cd airtable-mcp-server
   npm install

2. Get your Airtable Personal Access Token:

   • Visit https://airtable.com/create/tokens

   • Create a new token with read permissions for your target bases

   • Copy the token (format: patXXXXXXXXXXXXXX.xxxxxxxxxx...)

3. Configure environment:

   cp .env.example .env
   # Edit .env and set your AIRTABLE_PERSONAL_ACCESS_TOKEN

4. Build and test:

   npm run build
   npm start

Related MCP server: Airtable MCP Server

🔧 Usage

The server provides one tool: getAirtableRecord

Tool Parameters

Example Usage

Input:

{
  "recordId": "recABC123DEF456",
  "baseId": "appXYZ789ABC123",
  "tableName": "Artists"
}

Output:

{
  "content": [
    {
      "type": "text",
      "text": "{\"id\":\"recABC123DEF456\",\"fields\":{\"Name\":\"Vincent van Gogh\",\"Bio\":\"Dutch painter...\",\"Genre\":[\"Post-Impressionism\"]},\"createdTime\":\"2024-01-15T10:30:00.000Z\"}"
    }
  ]
}

🔗 MCP Client Integration

Claude Desktop

Add to your ~/.claude/mcp.json (see examples/claude-desktop.json):

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

Cursor IDE

Add to your .cursor/mcp.json (see examples/cursor-ide.json):

{
  "mcpServers": {
    "airtable": {
      "command": "node",
      "args": ["./dist/index.js"],
      "env": {
        "AIRTABLE_PERSONAL_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

VS Code

Add to your MCP configuration (see examples/vscode.json):

{
  "mcpServers": {
    "airtable": {
      "command": "node",
      "args": ["./dist/index.js"],
      "env": {
        "AIRTABLE_PERSONAL_ACCESS_TOKEN": "your_token_here"
      },
      "transport": "stdio"
    }
  }
}

Global Installation (NPM)

npm install -g airtable-mcp-server

# Then in your MCP client config:
{
  "command": "npx",
  "args": ["-y", "airtable-mcp-server@latest"]
}

🛠️ Development

Scripts

Project Structure

airtable-mcp-server/
├── src/
│   ├── index.ts              # Server entry point
│   ├── config/
│   │   ├── index.ts          # Configuration management
│   │   └── validation.ts     # Config validation
│   ├── tools/
│   │   ├── index.ts          # Tool registry
│   │   └── getRecord.ts      # Record retrieval tool
│   ├── types/
│   │   └── index.ts          # Type definitions
│   └── utils/
│       ├── error.ts          # Error handling
│       └── validation.ts     # Input validation
├── tests/
│   ├── integration.test.ts   # Integration tests
│   ├── unit/
│   │   └── tools.test.ts     # Unit tests
│   └── fixtures/
│       └── sample-record.json # Test data
├── examples/
│   ├── claude-desktop.json   # Claude Desktop config
│   ├── cursor-ide.json       # Cursor IDE config
│   ├── vscode.json           # VS Code config
│   └── usage.md              # Usage examples
├── docs/
│   └── DEPLOYMENT.md         # Deployment guide
├── dist/                     # Compiled JavaScript (generated)
├── PRD.md                    # Product requirements
├── CLAUDE.md                 # Claude Code guidance
├── package.json
├── tsconfig.json
├── .env.example
└── README.md

🔒 Security

Token Management

• Environment Only: Never commit tokens to version control

• Minimal Scope: Use read-only permissions for target bases only

• Token Rotation: Support for refreshing tokens when needed

Input Validation

• Record IDs must match pattern: rec[A-Za-z0-9]{14}

• Base IDs must match pattern: app[A-Za-z0-9]{14}

• Table names are sanitized for safe usage

Rate Limiting

• Respects Airtable's 5 requests/second per base limit

• Implements exponential backoff for rate limit errors

• Configurable retry attempts and delays

⚙️ Configuration

Environment variables:

🚨 Error Handling

The server handles various error scenarios:

All errors return structured responses with helpful messages.

📊 Performance

Requirements Met

• ✅ Response Time: <2 seconds for record retrieval

• ✅ Memory Usage: <50MB baseline footprint

• ✅ Concurrent Requests: Handles up to Airtable's rate limits

• ✅ Error Recovery: Graceful handling with exponential backoff

Monitoring

• Request/response logging to stderr

• Configuration validation on startup

• Structured error messages for debugging

🧪 Testing

Manual Testing

1. Valid Record Retrieval:

   # Replace with your actual IDs
   echo '{"recordId":"recYourRecordId","baseId":"appYourBaseId","tableName":"YourTable"}' | node dist/index.js

2. Error Scenarios:

   • Invalid record ID format

   • Non-existent record

   • Invalid base ID

   • Missing permissions

   • Rate limiting

Test Cases

The implementation includes comprehensive error handling for:

• ✅ Successful record retrieval

• ✅ Validation errors (invalid ID formats)

• ✅ Authentication failures (401/403)

• ✅ Not found errors (404)

• ✅ Rate limiting (429)

• ✅ Server errors (500+)

🔄 Future Enhancements

Planned Features

• Additional Tools: Create, update, delete operations

• Batch Operations: Multi-record processing

• Advanced Queries: Formula-based filtering

• Field Selection: Granular field retrieval

• HTTP Transport: REST API support

• Caching: Redis-based response caching

Production Features

• OAuth integration

• Multi-base support

• Audit logging

• High availability deployment

🆘 Troubleshooting

Common Issues

Server won't start:

• Check that AIRTABLE_PERSONAL_ACCESS_TOKEN is set

• Verify token has read permissions for target bases

• Ensure Node.js 18+ is installed

Authentication errors:

• Verify token is valid and not expired

• Check token has access to specified base

• Confirm base ID format: appXXXXXXXXXXXXXX

Record not found:

• Verify record ID format: recXXXXXXXXXXXXXX

• Check record exists in specified table

• Confirm table name is exactly correct (case-sensitive)

Rate limiting:

• Reduce request frequency

• Implement delays between requests

• Monitor Airtable usage limits

Debug Mode

Enable verbose logging:

DEBUG=* npm run dev

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests for new functionality

5. Submit a pull request

📚 Resources

• Model Context Protocol

• Airtable API Documentation

• Personal Access Token Setup

• TypeScript MCP SDK

Version: 1.0.0
Compatible with: Claude Desktop, Cursor IDE, VS Code MCP extensions
Node.js: 18+ required
Airtable API: Personal Access Token authentication