Frappe MCP Server

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"
    

Implementation Reference

• src/tools/reports.py:41-90 (handler)

  The main async handler function for executing the 'run_query_report' tool. It calls the Frappe API to run query reports with optional filters, formats the result as JSON, and handles errors.

  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:42-42 (registration)

  Registration of the reports tools module, which includes the run_query_report tool, by calling its register_tools function on the MCP server instance.

  reports.register_tools(mcp)

• src/tools/reports.py:16-35 (helper)

  Helper function used by run_query_report to format error responses consistently.

  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)}"