Airtable MCP Pro (Coolify-ready)

Vollständiger Airtable-Connector über MCP für ChatGPT Business / Projects.

• Tools: list_bases, list_tables, list_fields, query, search, fetch, create, update, delete, upsert

• Pagination (pageSize, offset), Sortierung, filterByFormula, fields[], view

• Rate-Limit-Handling (429 Retry mit Backoff), Logging

• Token-Strategie: Per-User via X-User-Token oder Workspace-Default AIRTABLE_TOKEN

Env

PORT=3000
AIRTABLE_TOKEN=pat_xxx             # Fallback; bevorzugt X-User-Token Header
AIRTABLE_BASE_ID=appXXXX           # optional Default base
AIRTABLE_TABLE=YourTable           # optional Default table
MCP_AUTH_TOKEN=change-me           # optional Connector-Bearer
LOG_LEVEL=info

Local run

npm ci
npm run dev
# health
curl http://localhost:3000/health
# list bases (requires token)
curl -X POST http://localhost:3000/mcp -H "Content-Type: application/json" -H "X-User-Token: $AIRTABLE_TOKEN" -d '{"tool":"list_bases","input":{}}'
# query with defaults
curl -X POST http://localhost:3000/mcp -H "Content-Type: application/json" -H "X-User-Token: $AIRTABLE_TOKEN" -d '{"tool":"query","input":{"pageSize":5}}'

Deploy (Coolify)

• Neues App (Dockerfile)

• ENV setzen (AIRTABLE_TOKEN optional, MCP_AUTH_TOKEN optional, Defaults)

• Domain/SSL → GET /health sollte { ok: true } liefern

• ChatGPT Business → Settings → Connectors → Create → URL https://<domain>/mcp

  • Wenn MCP_AUTH_TOKEN gesetzt: als Bearer im Connector hinterlegen

  • Publish → im Projekt aktivieren

Tools & Inputs (JSON)

• list_bases → {}

• list_tables → { "baseId": "app..." }

• list_fields → { "baseId": "app...", "tableIdOrName": "tbl...|Name" }

• query → { "baseId"?, "table"?, "view"?, "fields"?, "filterByFormula"?, "sort"?, "pageSize"?, "offset"? }

• search → { "query": "...", "baseId"?, "table"?, "field"?, "formula"?, "view"?, "fields"?, "sort"?, "pageSize"?, "offset"? }

• fetch → { "recordId": "rec...", "baseId"?, "table"? }

• create → { "records": [{ "fields": {...}}], "baseId"?, "table"?, "typecast"? }

• update → { "records": [{ "id": "rec...", "fields": {...}}], "baseId"?, "table"?, "typecast"? }

• delete → { "recordIds": ["rec..."], "baseId"?, "table"? }

• upsert → { "mergeField": "Email", "records": [{ "fields": {...}}], "baseId"?, "table"?, "typecast"? }

Hinweise

• Per-User-Auth: Der Connector kann im Request-Header X-User-Token einen PAT entgegennehmen (z. B. von ChatGPT gespeicherte User-Creds). Ohne diesen nutzt er AIRTABLE_TOKEN.

• Attachments: Über create/update kannst du Attachments per URL in ein Feld vom Typ „Attachment“ schreiben ({ fields: { Attachments: [{ url: "https://..." }] } }).

• Upsert: Nutzt mergeField (eindeutig!), holt bestehende Records und splittet in Create/Update.

• Limits: pageSize ≤ 100. Nutze die zurückgegebene offset, um zu paginieren.

Happy building 🚀