Empowering LLMs with Airtable: An Expert Guide to the Model Context Protocol Server

This document details the airtable-mcp-server, a crucial component for bridging the gap between Large Language Models (LLMs) and Airtable databases. By implementing the Model Context Protocol (MCP), this server allows LLMs to seamlessly access, interpret, and manipulate data within Airtable, unlocking powerful new AI-driven workflows.

Core Functionality

The airtable-mcp-server acts as an intermediary, translating LLM requests into Airtable API calls and vice versa. This enables LLMs to:

• Understand Airtable Schemas: Introspect database structures, including tables, fields, and their data types.
• Read and Write Data: Retrieve, create, update, and delete records within Airtable bases.
• Execute Complex Queries: Leverage Airtable's formula language for advanced filtering and data retrieval.

Integration with LLM Applications

To integrate this server with an LLM application like the Claude Desktop app, configure the mcpServers section of your application's configuration file (e.g., claude_desktop_config.json). Here's a sample configuration:

{
  "mcpServers": {
    "airtable": {
      "command": "npx",
      "args": [
        "-y",
        "airtable-mcp-server"
      ],
      "env": {
        "AIRTABLE_API_KEY": "pat123.abc123"
      }
    }
  }
}

Important: Replace pat123.abc123 with your actual Airtable personal access token. Ensure the token has the necessary permissions:

• schema.bases:read: Required for accessing database schemas.
• data.records:read: Required for reading data.
• data.records:write (Optional): Required for creating, updating, and deleting data.

Detailed Toolset

The server exposes a comprehensive set of tools, each designed for specific interactions with Airtable:

Data Retrieval

• list_records: Retrieves records from a specified table.
  • Parameters:
    • baseId (string, required): The Airtable base ID.
    • tableId (string, required): The table ID.
    • maxRecords (number, optional): Maximum records to return (default: 100).
    • filterByFormula (string, optional): Airtable formula for filtering.
• search_records: Searches for records containing specific text.
  • Parameters:
    • baseId (string, required): The Airtable base ID.
    • tableId (string, required): The table ID.
    • searchTerm (string, required): The text to search for.
    • fieldIds (array, optional): Specific field IDs to search within (searches all text fields if omitted).
    • maxRecords (number, optional): Maximum records to return (default: 100).
• get_record: Retrieves a specific record by its ID.
  • Parameters:
    • baseId (string, required): The Airtable base ID.
    • tableId (string, required): The table ID.
    • recordId (string, required): The record ID.

Schema Discovery

• list_bases: Lists all accessible Airtable bases.
  • Returns: Base ID, name, and permission level.
• list_tables: Lists all tables within a specified base.
  • Parameters:
    • baseId (string, required): The Airtable base ID.
    • detailLevel (string, optional): Level of detail to retrieve (tableIdentifiersOnly, identifiersOnly, or full).
  • Returns: Table ID, name, description, fields, and views (based on detailLevel).
• describe_table: Provides detailed information about a specific table.
  • Parameters:
    • baseId (string, required): The Airtable base ID.
    • tableId (string, required): The table ID.
    • detailLevel (string, optional): Level of detail to retrieve (tableIdentifiersOnly, identifiersOnly, or full).
  • Returns: Same format as list_tables but for a single table. Use this to get details about a specific table without fetching all tables in the base.

Data Manipulation

• create_record: Creates a new record in a table.
  • Parameters:
    • baseId (string, required): The Airtable base ID.
    • tableId (string, required): The table ID.
    • fields (object, required): An object containing field names and their corresponding values.
• update_records: Updates one or more records in a table.
  • Parameters:
    • baseId (string, required): The Airtable base ID.
    • tableId (string, required): The table ID.
    • records (array, required): An array of objects, each containing a recordId and a fields object with the updates.
• delete_records: Deletes one or more records from a table.
  • Parameters:
    • baseId (string, required): The Airtable base ID.
    • tableId (string, required): The table ID.
    • recordIds (array, required): An array of record IDs to delete.

Schema Modification

• create_table: Creates a new table in a base.
  • Parameters:
    • baseId (string, required): The Airtable base ID.
    • name (string, required): The name of the new table.
    • description (string, optional): A description of the table.
    • fields (array, required): An array of field definitions (name, type, description, options).
• update_table: Updates a table's name or description.
  • Parameters:
    • baseId (string, required): The Airtable base ID.
    • tableId (string, required): The table ID.
    • name (string, optional): The new name for the table.
    • description (string, optional): The new description for the table.
• create_field: Creates a new field in a table.
  • Parameters:
    • baseId (string, required): The Airtable base ID.
    • tableId (string, required): The table ID.
    • name (string, required): The name of the new field.
    • type (string, required): The type of the field.
    • description (string, optional): A description of the field.
    • options (object, optional): Field-specific options.
• update_field: Updates a field's name or description.
  • Parameters:
    • baseId (string, required): The Airtable base ID.
    • tableId (string, required): The table ID.
    • fieldId (string, required): The ID of the field.
    • name (string, optional): The new name for the field.
    • description (string, optional): The new description for the field.

Schema Resources

The server exposes schema information for Airtable bases and tables through a standardized URL format:

• Table Schemas: airtable://<baseId>/<tableId>/schema

This endpoint provides a JSON schema containing:

• Base and table IDs.
• Table name and description.
• Primary field ID.
• Field definitions (ID, name, type, description, options).
• View definitions (ID, name, type).

This schema information is automatically discovered from Airtable's metadata API, ensuring that LLMs always have access to the most up-to-date database structure.

Contributing to the Project

Contributions are highly encouraged! To contribute:

1. Install Git and Node.js.
2. Clone the repository.
3. Install dependencies: npm install.
4. Run tests: npm run test.
5. Build the project: npm run build. Use npm run build:watch for automatic rebuilding during development.

Release Management

This project adheres to semantic versioning. To create a new release:

1. Use npm version <major | minor | patch> to bump the version number.
2. Push the changes with tags: git push --follow-tags.
3. GitHub Actions will automatically publish the new version to the NPM registry.