Frappe MCP Server

Instructions

    Get the column structure for a specific report.
    
    Args:
        report_name: Name of the report
        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:284-331 (handler)

  The handler function for the 'get_report_columns' tool. It fetches column structure for a Frappe report using the API, with fallback to metadata, and handles errors.

  @mcp.tool()
  async def get_report_columns(
      report_name: str,
      filters: Optional[str] = None
  ) -> str:
      """
      Get the column structure for a specific report.
      
      Args:
          report_name: Name of the report
          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()
          
          # Get report columns using the report.get_columns method
          parsed_filters = format_filters_for_api(filters) or {}
          request_data = {
              "cmd": "frappe.desk.query_report.get_columns",
              "report_name": report_name,
              "filters": json.dumps(parsed_filters)
          }
          
          response = await client.post("api/method/frappe.desk.query_report.get_columns", json_data=request_data)
          
          if "message" in response:
              columns = response["message"]
              
              formatted_result = {
                  "report_name": report_name,
                  "columns": columns
              }
              
              return json.dumps(formatted_result, indent=2)
          else:
              # Fallback: get columns from report metadata
              meta_response = await client.get(f"api/resource/Report/{report_name}")
              if "data" in meta_response:
                  columns = meta_response["data"].get("columns", [])
                  return json.dumps({"report_name": report_name, "columns": columns}, indent=2)
              else:
                  return json.dumps(response, indent=2)
              
      except Exception as error:
          return _format_error_response(error, "get_report_columns")

• src/tools/reports.py:284-284 (registration)

  The @mcp.tool() decorator registers the get_report_columns function as an MCP tool.

  @mcp.tool()

• src/tools/reports.py:285-288 (schema)

  Input schema defined by function parameters with type hints: report_name (str, required), filters (Optional[str], optional). Output is str (JSON).

  async def get_report_columns(
      report_name: str,
      filters: Optional[str] = None
  ) -> str: