MCP Airtable Server

A Model Context Protocol (MCP) server that provides read-only access to Airtable workspaces. This server enables listing bases, tables, views, and records with comprehensive filtering and pagination support.

Features

Base Discovery

• List all bases in your workspace
• Get base schema with table and field information

Table Operations

• List tables in a base
• Get table schema including fields and field types

Record Reading

• List records with pagination support
• Get single record by ID
• Search records using Airtable formulas
• Filter and sort records with multiple criteria

View Support

• List views in a table
• Get records from specific views with view filters applied

Installation

Install the server using Claude Code:

# Install with user scope for global availability
claude mcp add airtable -s user -e AIRTABLE_ACCESS_TOKEN=your-token -- npx @chinchillaenterprises/mcp-airtable

# Or install with project scope for team sharing  
claude mcp add airtable -s project -e AIRTABLE_ACCESS_TOKEN=your-token -- npx @chinchillaenterprises/mcp-airtable

Authentication

This server requires an Airtable personal access token or OAuth token.

Getting Your Airtable Access Token

1. Go to airtable.com/create/tokens
2. Click "Create new token"
3. Give your token a name
4. Add the following scopes:
   • data.records:read - Read records
   • schema.bases:read - Read base schema
5. Add the bases you want to access
6. Click "Create token" and copy it

Environment Variable

Set your Airtable access token:

export AIRTABLE_ACCESS_TOKEN="patXXXXXXXXXXXXXX.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Available Tools

Base Discovery Tools

airtable_list_bases

List all accessible bases in your workspace.

No parameters required.

Returns: List of bases with IDs, names, and permission levels.

airtable_get_base_schema

Get complete schema for a base including all tables and fields.

Parameters:

• baseId (required): Airtable base ID (starts with 'app')

Table Operations Tools

airtable_list_tables

List all tables in a base.

Parameters:

• baseId (required): Airtable base ID (starts with 'app')

Returns: List of tables with names, IDs, and descriptions.

airtable_get_table_schema

Get detailed schema for a specific table.

Parameters:

• baseId (required): Airtable base ID (starts with 'app')
• tableId (required): Table ID or name

Returns: Table details including all fields with types and configurations.

Record Reading Tools

airtable_list_records

List records from a table with extensive filtering options.

Parameters:

• baseId (required): Airtable base ID (starts with 'app')
• tableId (required): Table ID or name
• maxRecords (optional): Maximum records to return (1-100, default: 100)
• pageSize (optional): Page size for pagination (1-100, default: 100)
• offset (optional): Pagination offset from previous response
• view (optional): View ID or name to use
• filterByFormula (optional): Airtable formula to filter records
• sort (optional): Array of sort configurations
• fields (optional): Array of field names to include

Example:

{
  "baseId": "appXXXXXXXXXXXXXX",
  "tableId": "Tasks",
  "filterByFormula": "AND({Status} = 'In Progress', {Priority} = 'High')",
  "sort": [
    { "field": "Due Date", "direction": "asc" }
  ],
  "fields": ["Name", "Status", "Due Date", "Assignee"]
}

airtable_get_record

Get a single record by ID.

Parameters:

• baseId (required): Airtable base ID (starts with 'app')
• tableId (required): Table ID or name
• recordId (required): Record ID (starts with 'rec')

airtable_search_records

Search records using Airtable formulas.

Parameters:

• baseId (required): Airtable base ID (starts with 'app')
• tableId (required): Table ID or name
• filterByFormula (required): Airtable formula to filter records
• maxRecords (optional): Maximum records to return
• sort (optional): Array of sort configurations
• fields (optional): Array of field names to include

Example formulas:

// Find records where Name contains "Project"
"SEARCH('Project', {Name})"

// Find records created this week
"IS_AFTER({Created}, DATEADD(TODAY(), -7, 'days'))"

// Complex filter with multiple conditions
"AND({Status} != 'Done', {Assignee} = 'John Doe', {Priority} > 3)"

View Support Tools

airtable_list_views

List all views in a table.

Parameters:

• baseId (required): Airtable base ID (starts with 'app')
• tableId (required): Table ID or name

Returns: List of views with names, IDs, and types.

airtable_get_view_records

Get records from a specific view with view filters applied.

Parameters:

• baseId (required): Airtable base ID (starts with 'app')
• tableId (required): Table ID or name
• viewId (required): View ID or name
• maxRecords (optional): Maximum records to return
• pageSize (optional): Page size for pagination
• offset (optional): Pagination offset
• fields (optional): Array of field names to include

Usage Examples

Basic Workflow: Explore a Base

// 1. List all bases
{
  "tool": "airtable_list_bases"
}

// 2. Get base schema
{
  "tool": "airtable_get_base_schema",
  "args": {
    "baseId": "appXXXXXXXXXXXXXX"
  }
}

// 3. List records from a table
{
  "tool": "airtable_list_records",
  "args": {
    "baseId": "appXXXXXXXXXXXXXX",
    "tableId": "Projects",
    "maxRecords": 10
  }
}

Advanced Search Example

// Search for high-priority tasks assigned to specific person
{
  "tool": "airtable_search_records",
  "args": {
    "baseId": "appXXXXXXXXXXXXXX",
    "tableId": "Tasks",
    "filterByFormula": "AND({Assignee} = 'Jane Smith', {Priority} = 'High', {Status} != 'Completed')",
    "sort": [
      { "field": "Due Date", "direction": "asc" }
    ],
    "fields": ["Task Name", "Due Date", "Status", "Notes"]
  }
}

Working with Views

// 1. List available views
{
  "tool": "airtable_list_views",
  "args": {
    "baseId": "appXXXXXXXXXXXXXX",
    "tableId": "Tasks"
  }
}

// 2. Get records from "This Week" view
{
  "tool": "airtable_get_view_records",
  "args": {
    "baseId": "appXXXXXXXXXXXXXX",
    "tableId": "Tasks",
    "viewId": "This Week",
    "fields": ["Task Name", "Assignee", "Due Date"]
  }
}

Pagination Example

// First page
{
  "tool": "airtable_list_records",
  "args": {
    "baseId": "appXXXXXXXXXXXXXX",
    "tableId": "Contacts",
    "pageSize": 50
  }
}

// Next page (using offset from previous response)
{
  "tool": "airtable_list_records",
  "args": {
    "baseId": "appXXXXXXXXXXXXXX",
    "tableId": "Contacts",
    "pageSize": 50,
    "offset": "itrXXXXXXXXXXXXXX/recXXXXXXXXXXXXXX"
  }
}

Airtable Formula Reference

Common formula patterns for filtering:

• Text matching: SEARCH('text', {Field Name})
• Exact match: {Field} = 'Value'
• Not equal: {Field} != 'Value'
• Greater/Less than: {Number Field} > 5
• Date comparisons: IS_AFTER({Date Field}, '2024-01-01')
• Empty check: {Field} = BLANK()
• Multiple conditions: AND(condition1, condition2) or OR(condition1, condition2)
• Checkbox fields: {Checkbox Field} = TRUE()

Error Handling

The server provides detailed error messages for common scenarios:

• Authentication errors: Invalid or expired access tokens
• Permission errors: Insufficient access to bases or tables
• Not found errors: Invalid base, table, or record IDs
• Invalid requests: Malformed formulas or parameters
• Rate limiting: Automatically handled with 5 requests/second limit

Rate Limiting

Airtable API has a rate limit of 5 requests per second. This server automatically:

• Queues requests to respect rate limits
• Adds delays between requests when needed
• Returns clear error messages if limits are exceeded

Testing

To test the server with your Airtable workspace:

1. Create a test base in Airtable
2. Add some sample tables and records
3. Generate an access token with appropriate scopes
4. Install and configure the MCP server
5. Use Claude to interact with your Airtable data

Local Development Testing

# 1. Install dependencies
cd mcp-airtable
npm install

# 2. Build the server
npm run build

# 3. Set your access token
export AIRTABLE_ACCESS_TOKEN="your-token-here"

# 4. Add server locally for testing
claude mcp add airtable-test -s user -- node $(pwd)/dist/index.js

# 5. Start Claude and test
claude
# Try: "List all my Airtable bases"

Limitations (v1.0.0)

This is a read-only server. The following operations are not supported:

• Creating records
• Updating records
• Deleting records
• Creating or modifying tables
• Creating or modifying views
• Modifying base structure

These write operations may be added in Phase 2.

Development

Prerequisites

• Node.js 18+
• TypeScript
• Airtable account with personal access token

Setup

git clone <repository>
cd mcp-airtable
npm install
npm run build

Building

npm run build          # Build once
npm run dev           # Build and watch for changes

Contributing

1. Follow the existing code structure and patterns
2. Add comprehensive error handling for new features
3. Update this README with new tools and examples
4. Test thoroughly with real Airtable data
5. Follow the ChillMCP conventions for consistency

License

MIT License - see LICENSE file for details.

Note: This MCP server provides read-only access to your Airtable data. Always ensure you're using appropriate access tokens with minimal required permissions.