Airtable OAuth MCP Server

Instructions

Implementation Reference

• src/airtable_mcp/mcp/server.py:331-359 (handler)

  MCP tool handler function for 'create_records' that authenticates, calls AirtableClient, and formats response.

  async def create_records(
      base_id: Annotated[str, Field(description="The Airtable base ID")],
      table_id: Annotated[str, Field(description="The table ID or name")],
      records: Annotated[
          list[dict[str, Any]], Field(description="List of records to create")
      ],
      typecast: Annotated[
          bool, Field(description="Enable automatic data conversion")
      ] = False,
  ) -> list[dict[str, Any]]:
      """Create multiple records in a table."""
      client = await self._get_authenticated_client()
  
      created_records = await client.create_records(
          base_id,
          table_id,
          records,
          typecast,
      )
  
      return [
          {
              "id": record.id,
              "fields": record.fields,
              "createdTime": record.created_time,
          }
          for record in created_records
      ]

• src/airtable_mcp/api/client.py:373-406 (helper)

  AirtableClient method implementing the core API call to create records in Airtable.

  async def create_records(
      self,
      base_id: str,
      table_id: str,
      records: list[dict[str, Any]],
      typecast: bool = False,
  ) -> list[AirtableRecord]:
      """Create new records in a table.
  
      Args:
          base_id: The Airtable base ID
          table_id: The table ID or name
          records: List of record data (each should have 'fields' key)
          typecast: Whether to enable automatic data conversion
  
      Returns:
          List of created records
      """
      logger.info(f"Creating {len(records)} records in {base_id}/{table_id}")
  
      request_data = CreateRecordsRequest(
          records=records,
          typecast=typecast,
      )
  
      response = await self._make_request(
          "POST",
          f"/v0/{base_id}/{table_id}",
          data=request_data.model_dump(by_alias=True, exclude_none=True),
          response_model=CreateRecordsResponse,
      )
  
      return response.records

• src/airtable_mcp/api/models.py:71-82 (schema)

  Pydantic models defining the request and response structure for create records API interactions.

  class CreateRecordsRequest(BaseModel):
      """Request for creating records."""
  
      records: list[dict[str, dict[str, Any]]]
      typecast: bool | None = False
  
  
  class CreateRecordsResponse(BaseModel):
      """Response from creating records."""
  
      records: list[AirtableRecord]

• src/airtable_mcp/mcp/server.py:331-359 (registration)

  Registration of the 'create_records' tool via FastMCP @tool decorator.

  async def create_records(
      base_id: Annotated[str, Field(description="The Airtable base ID")],
      table_id: Annotated[str, Field(description="The table ID or name")],
      records: Annotated[
          list[dict[str, Any]], Field(description="List of records to create")
      ],
      typecast: Annotated[
          bool, Field(description="Enable automatic data conversion")
      ] = False,
  ) -> list[dict[str, Any]]:
      """Create multiple records in a table."""
      client = await self._get_authenticated_client()
  
      created_records = await client.create_records(
          base_id,
          table_id,
          records,
          typecast,
      )
  
      return [
          {
              "id": record.id,
              "fields": record.fields,
              "createdTime": record.created_time,
          }
          for record in created_records
      ]

• src/airtable_mcp/mcp/schemas.py:73-82 (schema)

  Pydantic schema defining input arguments for the create_records tool (though not directly used in current implementation).

  class CreateRecordsArgs(BaseArgs):
      """Arguments for create_records tool."""
  
      base_id: str = Field(description="The Airtable base ID")
      table_id: str = Field(description="The table ID or name")
      records: list[dict[str, Any]] = Field(description="List of records to create")
      typecast: bool | None = Field(
          default=False, description="Enable automatic data conversion"
      )