Airtable OAuth MCP Server

Instructions

Implementation Reference

• src/airtable_mcp/mcp/server.py:302-329 (handler)

  The main MCP tool handler function for 'create_record'. It authenticates via OAuth, calls the AirtableClient.create_records method with a single record, and returns the created record details.

  @self.mcp.tool(description="Create a single record")
  async def create_record(
      base_id: Annotated[str, Field(description="The Airtable base ID")],
      table_id: Annotated[str, Field(description="The table ID or name")],
      fields: Annotated[
          dict[str, Any], Field(description="Field values for the new record")
      ],
      typecast: Annotated[
          bool, Field(description="Enable automatic data conversion")
      ] = False,
  ) -> dict[str, Any]:
      """Create a single record in a table."""
      client = await self._get_authenticated_client()
  
      records = await client.create_records(
          base_id,
          table_id,
          [{"fields": fields}],
          typecast,
      )
  
      record = records[0]
      return {
          "id": record.id,
          "fields": record.fields,
          "createdTime": record.created_time,
      }

• src/airtable_mcp/mcp/schemas.py:62-71 (schema)

  Pydantic schema defining the input arguments for the create_record tool, matching the handler's Annotated fields.

  class CreateRecordArgs(BaseArgs):
      """Arguments for create_record tool."""
  
      base_id: str = Field(description="The Airtable base ID")
      table_id: str = Field(description="The table ID or name")
      fields: dict[str, Any] = Field(description="Field values for the new record")
      typecast: bool | None = Field(
          default=False, description="Enable automatic data conversion"
      )

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

  The AirtableClient helper method that makes the actual POST request to Airtable's API to create records. Used by the create_record handler.

  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/mcp/server.py:123-123 (registration)

  The _register_tools method where all MCP tools, including create_record, are defined and registered using @self.mcp.tool decorators.

  def _register_tools(self) -> None: