mcpengine/servers/airtable/README.md

# @mcpengine/airtable

Complete Airtable MCP Server providing full API integration for bases, tables, records, fields, views, webhooks, automations, and comments.

## Features

- **Bases**: List and get base information
- **Tables**: List tables, get table schema with all fields and views
- **Records**: Full CRUD operations with filtering, sorting, and pagination
- **Fields**: Access field definitions and types (all 34 field types supported)
- **Views**: List and access views (grid, form, calendar, gallery, kanban, timeline, gantt)
- **Webhooks**: Create, list, refresh, and delete webhooks
- **Comments**: Full comment management on records
- **Rate Limiting**: Automatic retry with exponential backoff (5 req/sec per base)
- **Pagination**: Offset-based for records, cursor-based for metadata
- **Batch Operations**: Create/update/delete up to 10 records per request

## Installation

```bash
npm install @mcpengine/airtable
```

## Configuration

### Environment Variables

Create a `.env` file:

```bash
AIRTABLE_API_KEY=your_api_key_here
```

Get your API key from: https://airtable.com/create/tokens

### MCP Settings

Add to your MCP settings file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "airtable": {
      "command": "node",
      "args": ["/path/to/@mcpengine/airtable/dist/main.js"],
      "env": {
        "AIRTABLE_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

## Usage

### List Bases

```typescript
// Returns all bases accessible with the API key
airtable_list_bases({ offset?: string })
```

### List Tables

```typescript
// Get all tables in a base with schema
airtable_list_tables({ baseId: "appXXXXXXXXXXXXXX" })
```

### List Records

```typescript
// List records with filtering, sorting, and pagination
airtable_list_records({
  baseId: "appXXXXXXXXXXXXXX",
  tableIdOrName: "tblXXXXXXXXXXXXXX" || "Table Name",
  fields?: ["Field1", "Field2"],
  filterByFormula?: "{Status} = 'Done'",
  sort?: [{ field: "Name", direction: "asc" }],
  maxRecords?: 100,
  pageSize?: 100,
  view?: "Grid view",
  offset?: "itrXXXXXXXXXXXXXX/recXXXXXXXXXXXXXX"
})
```

### Create Records

```typescript
// Create up to 10 records at once
airtable_create_records({
  baseId: "appXXXXXXXXXXXXXX",
  tableIdOrName: "tblXXXXXXXXXXXXXX",
  records: [
    { fields: { Name: "John Doe", Email: "john@example.com" } },
    { fields: { Name: "Jane Smith", Email: "jane@example.com" } }
  ],
  typecast?: true  // Auto-convert types
})
```

### Update Records

```typescript
// Update up to 10 records at once
airtable_update_records({
  baseId: "appXXXXXXXXXXXXXX",
  tableIdOrName: "tblXXXXXXXXXXXXXX",
  records: [
    { id: "recXXXXXXXXXXXXXX", fields: { Status: "Complete" } }
  ],
  typecast?: true
})
```

### Delete Records

```typescript
// Delete up to 10 records at once
airtable_delete_records({
  baseId: "appXXXXXXXXXXXXXX",
  tableIdOrName: "tblXXXXXXXXXXXXXX",
  recordIds: ["recXXXXXXXXXXXXXX", "recYYYYYYYYYYYYYY"]
})
```

### Webhooks

```typescript
// Create a webhook
airtable_create_webhook({
  baseId: "appXXXXXXXXXXXXXX",
  notificationUrl: "https://your-server.com/webhook",
  specification: {
    options: {
      filters: {
        dataTypes: ["tableData"],
        recordChangeScope: "tblXXXXXXXXXXXXXX"
      }
    }
  }
})

// Refresh webhook (extends expiration)
airtable_refresh_webhook({
  baseId: "appXXXXXXXXXXXXXX",
  webhookId: "achXXXXXXXXXXXXXX"
})
```

### Comments

```typescript
// Create a comment on a record
airtable_create_comment({
  baseId: "appXXXXXXXXXXXXXX",
  tableIdOrName: "tblXXXXXXXXXXXXXX",
  recordId: "recXXXXXXXXXXXXXX",
  text: "This is a comment"
})
```

## Supported Field Types

All 34 Airtable field types are fully supported:

- **Text**: singleLineText, email, url, multilineText, richText, phoneNumber
- **Number**: number, percent, currency, rating, duration, autoNumber
- **Select**: singleSelect, multipleSelects
- **Date**: date, dateTime, createdTime, lastModifiedTime
- **Attachment**: multipleAttachments
- **Link**: multipleRecordLinks
- **User**: singleCollaborator, multipleCollaborators, createdBy, lastModifiedBy
- **Computed**: formula, rollup, count, lookup, multipleLookupValues
- **Other**: checkbox, barcode, button, externalSyncSource, aiText

## API Limits

- **Rate Limit**: 5 requests per second per base
- **Batch Create/Update**: Max 10 records per request
- **Batch Delete**: Max 10 record IDs per request
- **Page Size**: Max 100 records per page

Rate limiting is handled automatically with exponential backoff.

## Development

```bash
# Install dependencies
npm install

# Type check
npm run typecheck

# Build
npm run build

# Run
npm start
```

## Architecture

```
src/
├── types/index.ts       # All Airtable API types (bases, tables, records, fields, etc.)
├── clients/airtable.ts  # API client with rate limiting and pagination
├── server.ts            # MCP server with lazy-loaded tools
└── main.ts              # Entry point with dual transport support
```

## License

MIT

## Resources

- [Airtable API Documentation](https://airtable.com/developers/web/api/introduction)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [Create API Token](https://airtable.com/create/tokens)