README.md•3.04 kB
# 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
```bash
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 🚀