Enhanced Airtable MCP Server

A robust Model Context Protocol (MCP) server for Airtable that properly handles all field types including single select, dates, formulas, checkboxes, numbers, and more.

Features

• Full Field Type Support: Properly handles all Airtable field types:

  • Single Select & Multiple Selects
  • Date & DateTime
  • Number, Currency, Percent, Duration, Rating
  • Checkbox (Boolean)
  • Email, URL, Phone Number
  • Attachments
  • Record Links
  • Formula, Rollup, Lookup (read-only)
  • And more!

• Automatic Type Conversion: Automatically converts values to the correct format based on field type

• Validation: Validates field values against schema (e.g., validates select options)

• Flexible Querying: Support for filtering, sorting, views, and field selection

• Schema Management: Auto-fetch table schemas from Airtable Metadata API or define manually

• Batch Operations: Efficiently create, update, or delete up to 10 records per request

• Discovery Tools: List all accessible bases and tables with metadata

Installation

npm install
npm run build

Configuration

Authentication

This server uses Personal Access Tokens (PAT) for authentication. Airtable is deprecating legacy API keys in favor of PATs.

Personal Access Tokens:

• Start with pat (e.g., patXXXXXXXXXXXXXXXXXX.XXXXXXXXX...)
• Can access multiple bases with a single token
• Support fine-grained permissions
• Optionally set AIRTABLE_BASE_ID for a default base

Environment Variables:

• AIRTABLE_PAT (required): Your Personal Access Token
• AIRTABLE_BASE_ID (optional): Default base ID if you primarily work with one base

Create your PAT: https://airtable.com/create/tokens

Note: Legacy API keys (starting with key) are no longer supported by this server.

Security Best Practices

⚠️ IMPORTANT: Never commit tokens to version control!

1. Use Environment Variables: Store credentials in .env file (already in .gitignore)
2. Rotate Tokens Regularly: Refresh Personal Access Tokens every 90 days
3. Use Scoped Permissions: Create PATs with minimum required permissions (scopes)
4. Separate Environments: Use different tokens for dev/staging/production

See SECURITY.md for comprehensive security guidelines.

Usage

Running Locally

# Development mode with PAT only (access multiple bases)
AIRTABLE_PAT=your_pat npm run dev

# Development mode with default base
AIRTABLE_PAT=your_pat AIRTABLE_BASE_ID=your_base npm run dev

# Production mode
AIRTABLE_PAT=your_pat AIRTABLE_BASE_ID=your_base npm start

Using with Claude Desktop

Add to your Claude Desktop configuration file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

Option 1: PAT Only (Multi-base Access)

{
  "mcpServers": {
    "airtable": {
      "command": "node",
      "args": ["/absolute/path/to/airtable-mcp-server/build/index.js"],
      "env": {
        "AIRTABLE_PAT": "patXXXXXXXXXXXXXXXXXX.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
      }
    }
  }
}

With this setup, the server can access all bases your PAT has permissions for.

Option 2: PAT with Default Base (Recommended)

If you primarily work with one base:

{
  "mcpServers": {
    "airtable": {
      "command": "node",
      "args": ["/absolute/path/to/airtable-mcp-server/build/index.js"],
      "env": {
        "AIRTABLE_PAT": "patXXXXXXXXXXXXXXXXXX.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "AIRTABLE_BASE_ID": "appXXXXXXXXXXXXXX"
      }
    }
  }
}

Security Notes:

• ⚠️ Use absolute paths only (e.g., /Users/you/projects/... not ~/projects/...)
• 🔒 Protect config file: chmod 600 ~/Library/Application\ Support/Claude/claude_desktop_config.json
• 🚫 Never commit this config file with real credentials
• ✅ Claude Desktop config file is user-specific and should stay private

Available Tools

1. airtable_list_bases

List all Airtable bases accessible with your Personal Access Token.

Parameters: None

Example Response:

{
  "count": 3,
  "bases": [
    {
      "id": "appXXXXXXXXXXXXXX",
      "name": "My Project",
      "permissionLevel": "create"
    }
  ]
}

2. airtable_list_tables

List all tables in an Airtable base.

Parameters:

• baseId (optional): Airtable base ID. If not provided, uses the default base from configuration.

Example Response:

{
  "count": 5,
  "tables": [
    {
      "id": "tblXXXXXXXXXXXXXX",
      "name": "Contacts",
      "description": "Customer contact information",
      "primaryFieldId": "fldXXXXXXXXXXXXXX"
    }
  ]
}

3. airtable_get_table_schema

Get the complete schema for a table including all field definitions, types, and options. Auto-fetches from Airtable Metadata API.

Parameters:

• baseId (optional): Airtable base ID
• table (required): Table name

Example:

{
  "table": "Tasks"
}

4. airtable_list_records

List records from a table with optional filtering and sorting.

Parameters:

• table (required): Table name
• filterByFormula (optional): Airtable formula for filtering
• maxRecords (optional): Maximum records to return
• view (optional): View name to use
• fields (optional): Array of field names to return
• sort (optional): Array of sort objects [{field: "Name", direction: "asc"}]

Example:

{
  "table": "Contacts",
  "filterByFormula": "{Status} = 'Active'",
  "maxRecords": 10,
  "sort": [{"field": "Created", "direction": "desc"}]
}

5. airtable_get_record

Get a specific record by ID.

Parameters:

• table (required): Table name
• recordId (required): Record ID

6. airtable_create_record

Create a new record with automatic field type conversion.

Parameters:

• table (required): Table name
• fields (required): Object with field values

Example:

{
  "table": "Tasks",
  "fields": {
    "Name": "Complete project",
    "Status": "In Progress",
    "Due Date": "2024-12-31",
    "Priority": 5,
    "Completed": false
  }
}

7. airtable_update_record

Update an existing record.

Parameters:

• table (required): Table name
• recordId (required): Record ID
• fields (required): Object with field values to update

8. airtable_delete_record

Delete a record.

Parameters:

• table (required): Table name
• recordId (required): Record ID

9. airtable_set_table_schema

Define the schema for a table to enable proper field type handling. This is optional but recommended for better type safety and validation.

Parameters:

• table (required): Table name
• fields (required): Array of field definitions

Example:

{
  "table": "Tasks",
  "fields": [
    {
      "name": "Name",
      "type": "singleLineText"
    },
    {
      "name": "Status",
      "type": "singleSelect",
      "options": {
        "choices": [
          {"id": "sel1", "name": "To Do"},
          {"id": "sel2", "name": "In Progress"},
          {"id": "sel3", "name": "Done"}
        ]
      }
    },
    {
      "name": "Due Date",
      "type": "date"
    },
    {
      "name": "Priority",
      "type": "number"
    },
    {
      "name": "Completed",
      "type": "checkbox"
    }
  ]
}

10. airtable_batch_create_records

Create multiple records at once (up to 10 per request). Much more efficient than creating records individually.

Parameters:

• baseId (optional): Airtable base ID
• table (required): Table name
• records (required): Array of record objects (max 10)

Example:

{
  "table": "Tasks",
  "records": [
    {
      "Name": "Task 1",
      "Status": "To Do",
      "Priority": 3
    },
    {
      "Name": "Task 2",
      "Status": "In Progress",
      "Priority": 5
    },
    {
      "Name": "Task 3",
      "Status": "To Do",
      "Priority": 1
    }
  ]
}

11. airtable_batch_update_records

Update multiple records at once (up to 10 per request). Much more efficient than updating records individually.

Parameters:

• baseId (optional): Airtable base ID
• table (required): Table name
• updates (required): Array of update objects with id and fields (max 10)

Example:

{
  "table": "Tasks",
  "updates": [
    {
      "id": "recXXXXXXXXXXXXXX",
      "fields": {
        "Status": "Completed",
        "Completed": true
      }
    },
    {
      "id": "recYYYYYYYYYYYYYY",
      "fields": {
        "Status": "In Progress",
        "Priority": 5
      }
    }
  ]
}

12. airtable_batch_delete_records

Delete multiple records at once (up to 10 per request). Much more efficient than deleting records individually.

Parameters:

• baseId (optional): Airtable base ID
• table (required): Table name
• recordIds (required): Array of record IDs to delete (max 10)

Example:

{
  "table": "Tasks",
  "recordIds": [
    "recXXXXXXXXXXXXXX",
    "recYYYYYYYYYYYYYY",
    "recZZZZZZZZZZZZZZ"
  ]
}

Field Type Handling

The server automatically converts values based on field types:

Field Type	Input Format	Notes
singleSelect	"Option Name"	Validates against available choices
multipleSelects	["Option1", "Option2"]	Array of option names
date/dateTime	"2024-12-31" or ISO string	Converts to ISO format
number/currency/percent	42 or "42"	Converts to number
checkbox	true, false, "true", "1"	Converts to boolean
email	"user@example.com"	Validates email format
url	"https://example.com"	Validates URL format
multipleRecordLinks	["recXXX", "recYYY"]	Array of record IDs
attachment	[{url: "https://..."}]	Array of attachment objects
formula/rollup/etc.	N/A	Read-only fields

Development

# Install dependencies
npm install

# Run in development mode with auto-reload
npm run dev

# Build TypeScript
npm run build

# Watch mode for development
npm run watch

Project Structure

.
├── src/
│   ├── index.ts                 # Main MCP server
│   ├── types/
│   │   └── airtable.ts         # Type definitions
│   ├── utils/
│   │   ├── airtable-client.ts  # Airtable client wrapper
│   │   └── field-converter.ts  # Field type conversion utilities
│   └── handlers/                # Future: tool handlers
├── build/                       # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

Why This Server?

The existing Airtable MCP servers only work with simple text fields. This server:

• Properly handles single select fields (validates options)
• Correctly formats date and datetime fields
• Converts number, currency, percent fields appropriately
• Handles checkbox (boolean) fields
• Supports multiple selects, attachments, record links
• Validates field values against schema
• Provides helpful error messages

Security

This MCP server implements comprehensive security measures:

✅ Input Validation: All inputs validated with Zod schemas ✅ Formula Injection Protection: Sanitized field names and escaped values ✅ Error Sanitization: Sensitive data redacted from error messages ✅ Field Filtering: Automatic exclusion of large/sensitive fields ✅ Rate Limit Awareness: Respects Airtable API limits ✅ Dependency Scanning: Regular npm audit checks (currently 0 vulnerabilities)

For security issues: Please review SECURITY.md and report vulnerabilities privately to maintainers (not via public issues).

Best Practices for Claude Desktop

Always use field filtering to prevent timeouts and protect sensitive data:

{
  "table": "Users",
  "excludeAttachments": true,  // ⭐ ALWAYS use this with Claude Desktop
  "maxRecords": 100
}

Or use presets for common scenarios:

{
  "table": "Contacts",
  "preset": "contact",  // Safe preset (no attachments/long text)
  "maxRecords": 50
}

Monitor API Usage

Airtable limits:

• 5 requests/second per base
• 100,000 calls/day per workspace

Check your usage in the Airtable Account Dashboard.

License

MIT

Contributing

Contributions are welcome! Please:

1. Review SECURITY.md for security guidelines
2. Run npm audit before submitting
3. Add tests for new features
4. Follow existing code style

For security vulnerabilities, please follow the private disclosure process in SECURITY.md.