list_documents
Retrieve documents from Frappe with customizable filters, field selection, and sorting options to locate specific records efficiently.
Instructions
List documents from Frappe with filters.
Args:
doctype: DocType name
filters: Filter string (optional). Uses custom syntax to bypass MCP validation issues.
fields: Comma-separated field names (optional). E.g. "name,customer,total"
limit: Maximum number of records to return (optional). E.g. "20"
order_by: Field to order by (optional, can include 'desc' like 'creation desc')
Filter Syntax:
- Simple equality: "field:value" -> {"field": "value"}
- Operators: "field:operator:value" -> {"field": ["operator", value]}
- Multiple filters: "field1:value1,field2:operator:value2"
Supported Operators:
- Equality: = (default), !=
- Comparison: <, >, <=, >=
- Pattern: like, not_like (use % for wildcards)
- Lists: in, not_in (separate values with |)
- Null checks: is:null, is:not_null, is_not:null
- Ranges: between (separate values with |)
Examples:
- list_documents("Bank Transaction", "status:Unreconciled") -> List unreconciled transactions
- list_documents("Task", "status:in:Open|Working", "name,subject", "10") -> List open tasks with specific fields
- list_documents("User", "name:like:%admin%") -> List users with 'admin' in name
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| doctype | Yes | ||
| filters | No | ||
| fields | No | ||
| limit | No | ||
| order_by | No |
Implementation Reference
- src/tools/documents.py:350-416 (handler)The core handler function for the 'list_documents' MCP tool. It queries the Frappe REST API (/api/resource/{doctype}) with parsed filters, optional fields, limit, and order_by. Formats results as a count and JSON dump of documents.@mcp.tool() async def list_documents( doctype: str, filters: Optional[str] = None, fields: Optional[str] = None, limit: Optional[str] = None, order_by: Optional[str] = None ) -> str: """ List documents from Frappe with filters. Args: doctype: DocType name filters: Filter string (optional). Uses custom syntax to bypass MCP validation issues. fields: Comma-separated field names (optional). E.g. "name,customer,total" limit: Maximum number of records to return (optional). E.g. "20" order_by: Field to order by (optional, can include 'desc' like 'creation desc') Filter Syntax: - Simple equality: "field:value" -> {"field": "value"} - Operators: "field:operator:value" -> {"field": ["operator", value]} - Multiple filters: "field1:value1,field2:operator:value2" Supported Operators: - Equality: = (default), != - Comparison: <, >, <=, >= - Pattern: like, not_like (use % for wildcards) - Lists: in, not_in (separate values with |) - Null checks: is:null, is:not_null, is_not:null - Ranges: between (separate values with |) Examples: - list_documents("Bank Transaction", "status:Unreconciled") -> List unreconciled transactions - list_documents("Task", "status:in:Open|Working", "name,subject", "10") -> List open tasks with specific fields - list_documents("User", "name:like:%admin%") -> List users with 'admin' in name """ try: client = get_client() # Build query parameters params = {} parsed_filters = format_filters_for_api(filters) if parsed_filters: params["filters"] = json.dumps(parsed_filters) if fields: # Convert comma-separated string to list field_list = [f.strip() for f in fields.split(',')] params["fields"] = json.dumps(field_list) if limit: # Convert string to integer for API params["limit"] = limit if order_by: params["order_by"] = order_by # Make API request to list documents response = await client.get(f"api/resource/{doctype}", params=params) if "data" in response: documents = response["data"] count = len(documents) return f"Found {count} {doctype} documents:\n\n" + json.dumps(documents, indent=2) else: return json.dumps(response, indent=2) except Exception as error: return _format_error_response(error, "list_documents")
- src/server.py:40-40 (registration)Top-level registration call in the MCP server setup that invokes documents.register_tools(mcp), which defines and registers the list_documents tool among other document tools.documents.register_tools(mcp)
- src/tools/documents.py:81-81 (registration)The register_tools function in documents.py that defines all document-related MCP tools using @mcp.tool() decorators, including the list_documents handler. This function is called from src/server.py.def register_tools(mcp: Any) -> None:
- src/tools/documents.py:351-357 (schema)Input schema defined by function parameters with type hints: doctype (required str), optional filters/fields/limit/order_by (str), returns formatted str response. Detailed usage in docstring.async def list_documents( doctype: str, filters: Optional[str] = None, fields: Optional[str] = None, limit: Optional[str] = None, order_by: Optional[str] = None ) -> str:
- src/tools/documents.py:13-13 (helper)Imports format_filters_for_api helper from filter_parser.py, used at line 391 to parse custom filter strings into Frappe API filter JSON.from .filter_parser import format_filters_for_api, FILTER_SYNTAX_DOCS