MCP Airtable

Production-ready MCP server for Airtable integration

Built with FastMCP — Works with Claude Desktop & Claude.ai

Overview

A minimal, enterprise-grade MCP server enabling AI assistants to interact with Airtable. Features 21 tools covering complete CRUD operations, batch processing, schema management, and file attachments—built with meticulous precision and strategic clarity.

Related MCP server: Airtable MCP Server

Δ Capabilities

Core

21 Tools — Full CRUD, batch operations, attachments Streamable HTTP — Claude Desktop 2025+ native support Header Auth — Multi-tenant ready architecture

Reliability

Circuit Breaker — Cascading failure prevention Auto-Retry — Exponential backoff with jitter Health Checks — K8s liveness & readiness probes

Security

Input Validation — Zod schemas everywhere Injection Prevention — Formula & path attacks blocked Audit Ready — Full security documentation

Performance

Connection Pooling — Keep-alive via undici Request Deduplication — Shares concurrent results Response Caching — 5-10min TTL for metadata

Quick Start

npm install && npm run build
npm start

Server runs at http://localhost:3000/mcp

Configuration

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

{
  "mcpServers": {
    "mcp-airtable": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://your-server.com/mcp",
        "--header", "x-airtable-api-key:patXXXXX.XXXXX...",
        "--header", "x-airtable-workspace-id:wspXXXXXXXXXXX"
      ]
    }
  }
}

1. Deploy: npm start

2. Claude.ai → Settings → Connectors

3. Add URL: https://your-server.com/mcp

4. Add header: x-airtable-api-key: patXXXXX...

→ Get your API key

β Tools

° Enterprise Scale plan required

Usage

"List all my Airtable bases"

"Get records from Tasks where Status = 'Active'"

"Create a task with Name='Review PR' and Priority='High'"

"Upload the PDF to the Attachments field on record rec123"

Authentication

Airtable Plan Requirements

° Returns 404 on non-Enterprise plans. Workaround: Get workspace ID from Airtable UI URL (airtable.com/wspXXX/...)

Stability & Resilience

• Auto-retries on HTTP 429, 500, 502, 503, 504

• Handles network errors (ECONNRESET, ETIMEDOUT, ECONNREFUSED)

• Respects Retry-After headers

• Configurable max retries, delays, jitter

Prevents cascading failures:

• CLOSED — Normal operation

• OPEN — Fast-fail mode

• HALF_OPEN — Recovery testing

• Timeout: 30s default (AbortController)

• Deduplication: Shares identical concurrent GETs

• Queue: Limits to 5 concurrent requests

• Keep-Alive: Connection pooling via undici

Kubernetes-ready probes:

• health_check — Full status report

• liveness — Alive check

• readiness — Traffic ready

Deployment

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY dist ./dist
EXPOSE 3000
CMD ["node", "dist/index.js"]

docker build -t mcp-airtable .
docker run -p 3000:3000 mcp-airtable

# Server
PORT=3000
NODE_ENV=production

# Auth (prefer headers in production)
AIRTABLE_API_KEY=
AIRTABLE_WORKSPACE_ID=

# Rate Limiting
RATE_LIMIT_ENABLED=true
RATE_LIMIT_REQUESTS_PER_MINUTE=60

# Caching
CACHE_ENABLED=true
CACHE_TTL_BASES=300
CACHE_TTL_SCHEMA=600
CACHE_TTL_TABLES=300

# Logging
LOG_LEVEL=info

# Sentry (Optional)
SENTRY_DSN=
SENTRY_DEBUG=false
SENTRY_ENVIRONMENT=production

Architecture

src/
├── index.ts                 # Entry point
├── server.ts                # FastMCP init
├── tools/                   # 21 tools
│   ├── bases.ts
│   ├── tables.ts
│   ├── fields.ts
│   ├── records.ts
│   ├── batch.ts
│   └── comments.ts
└── lib/                     # Core
    ├── airtable/            # API client
    ├── retry.ts             # Backoff
    ├── circuit-breaker.ts   # Failure prevention
    ├── health.ts            # K8s probes
    ├── deduplication.ts     # Request dedup
    └── ...

~2,500 lines · 272 unit tests · 25 e2e tests

References

Security · Examples · Changelog

MIT License

DELTΔ & βETΑ

From Change to What's Next