search_records
Search Airtable records by applying a formula filter to retrieve data from specific bases, tables, and views. Use fields parameter to include only relevant data in results.
Instructions
Search records using a formula filter
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| base_id | Yes | The Airtable base ID | |
| fields | No | Specific fields to include (field name or array of field names) | |
| filter_by_formula | Yes | Airtable formula for filtering | |
| table_id | Yes | The table ID or name | |
| view | No | View name or ID |
Implementation Reference
- src/airtable_mcp/mcp/server.py:409-466 (handler)The main MCP tool handler function for 'search_records', registered using the @self.mcp.tool decorator. It authenticates a client, normalizes fields, constructs options, calls the client search method, and formats the response.@self.mcp.tool(description="Search records using a formula filter") async def search_records( base_id: Annotated[str, Field(description="The Airtable base ID")], table_id: Annotated[str, Field(description="The table ID or name")], filter_by_formula: Annotated[ str, Field(description="Airtable formula for filtering") ], view: Annotated[str | None, Field(description="View name or ID")] = None, fields: Annotated[ str | list[str] | None, Field( description="Specific fields to include (field name or array of field names)" ), ] = None, ) -> list[dict[str, Any]]: """Search records using a formula filter.""" client = await self._get_authenticated_client() # Normalize fields parameter normalized_fields = None if fields is not None: if isinstance(fields, str): # Check if it's a JSON-encoded array string if fields.startswith("[") and fields.endswith("]"): try: import json normalized_fields = json.loads(fields) except (json.JSONDecodeError, ValueError): # If JSON parsing fails, treat as single field name normalized_fields = [fields] else: # Single field name normalized_fields = [fields] else: normalized_fields = fields options = ListRecordsOptions( view=view, fields=normalized_fields, ) records = await client.search_records( base_id, table_id, filter_by_formula, options, ) return [ { "id": record.id, "fields": record.fields, "createdTime": record.created_time, } for record in records ]
- Pydantic schema class defining the input arguments for the search_records tool, including base_id, table_id, filter_by_formula, and optional parameters.class SearchRecordsArgs(BaseArgs): """Arguments for search_records tool.""" base_id: str = Field(description="The Airtable base ID") table_id: str = Field(description="The table ID or name") filter_by_formula: str = Field(description="Airtable formula for filtering") max_records: int | None = Field( default=None, description="Maximum number of records to return" ) view: str | None = Field(default=None, description="View name or ID") fields: list[str] | None = Field( default=None, description="Specific fields to include" )
- Helper method in AirtableClient that performs the actual search by setting filter_by_formula on ListRecordsOptions and delegating to list_records method.async def search_records( self, base_id: str, table_id: str, filter_by_formula: str, options: ListRecordsOptions | None = None, ) -> list[AirtableRecord]: """Search records using a formula filter. Args: base_id: The Airtable base ID table_id: The table ID or name filter_by_formula: Airtable formula for filtering options: Additional options for the search Returns: List of matching records """ logger.info( f"Searching records in {base_id}/{table_id} with formula: {filter_by_formula}" ) # Merge filter with existing options search_options = options or ListRecordsOptions() search_options.filter_by_formula = filter_by_formula return await self.list_records(base_id, table_id, search_options)