@chinchillaenterprises/mcp-airtable

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

• Go to airtable.com/create/tokens
• Click "Create new token"
• Give your token a name
• Add the following scopes:
  • data.records:read - Read records
  • schema.bases:read - Read base schema
• Add the bases you want to access
• 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:

• Create a test base in Airtable
• Add some sample tables and records
• Generate an access token with appropriate scopes
• Install and configure the MCP server
• 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

• Follow the existing code structure and patterns
• Add comprehensive error handling for new features
• Update this README with new tools and examples
• Test thoroughly with real Airtable data
• 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.