run_query_report
Execute Frappe query reports with custom filters to extract specific data from Frappe Framework sites using string-based filter syntax.
Instructions
Execute a Frappe query report with filters.
Args:
report_name: Name of the report to run
filters: Filter string (optional). Uses custom syntax to bypass MCP validation issues.
Filter Syntax: Use the same string-based syntax as count_documents and list_documents.
Examples: "status:Open", "date:>=:2025-01-01", "status:in:Open|Working"
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| filters | No | ||
| report_name | Yes |
Implementation Reference
- src/tools/reports.py:40-90 (handler)Handler function for the 'run_query_report' tool. Executes Frappe query reports via API, handles filters, formats results as JSON, and manages errors.@mcp.tool() async def run_query_report( report_name: str, filters: Optional[str] = None ) -> str: """ Execute a Frappe query report with filters. Args: report_name: Name of the report to run filters: Filter string (optional). Uses custom syntax to bypass MCP validation issues. Filter Syntax: Use the same string-based syntax as count_documents and list_documents. Examples: "status:Open", "date:>=:2025-01-01", "status:in:Open|Working" """ try: client = get_client() # Prepare request data parsed_filters = format_filters_for_api(filters) or {} request_data = { "cmd": "frappe.desk.query_report.run", "report_name": report_name, "filters": json.dumps(parsed_filters), "ignore_prepared_report": 1 } # Run the report response = await client.post("api/method/frappe.desk.query_report.run", json_data=request_data) if "message" in response: result = response["message"] # Format the response columns = result.get("columns", []) data = result.get("result", []) formatted_result = { "report_name": report_name, "columns": columns, "data": data, "row_count": len(data) } return json.dumps(formatted_result, indent=2) else: return json.dumps(response, indent=2) except Exception as error: return _format_error_response(error, "run_query_report")
- src/server.py:38-42 (registration)Top-level registration of all tool modules, including reports.register_tools(mcp) which registers the 'run_query_report' tool.# Register all tool modules helpers.register_tools(mcp) documents.register_tools(mcp) schema.register_tools(mcp) reports.register_tools(mcp)
- src/tools/reports.py:16-35 (helper)Helper function used by run_query_report for formatting error responses with credential checks and specific error handling.def _format_error_response(error: Exception, operation: str) -> str: """Format error response with detailed information.""" credentials_check = validate_api_credentials() # Check for missing credentials first if not credentials_check["valid"]: error_msg = f"Authentication failed: {credentials_check['message']}. " error_msg += "API key/secret is the only supported authentication method." return error_msg # Handle FrappeApiError if isinstance(error, FrappeApiError): error_msg = f"Frappe API error: {error}" if error.status_code in (401, 403): error_msg += " Please check your API key and secret." return error_msg # Default error handling return f"Error in {operation}: {str(error)}"