Frappe MCP Server

Instructions

    Get standard financial reports (P&L, Balance Sheet, Cash Flow).
    
    Args:
        report_type: Type of financial statement 
                   ('Profit and Loss Statement', 'Balance Sheet', 'Cash Flow')
        company: Company name
        from_date: Start date (YYYY-MM-DD format, optional)
        to_date: End date (YYYY-MM-DD format, optional) 
        periodicity: Periodicity (Monthly, Quarterly, Half-Yearly, Yearly)
    

Implementation Reference

• src/tools/reports.py:222-282 (handler)

  The core handler function for the 'get_financial_statements' MCP tool. It executes Frappe query reports for financial statements by posting to frappe.desk.query_report.run with appropriate filters.

  @mcp.tool()
  async def get_financial_statements(
      report_type: str,
      company: str,
      from_date: Optional[str] = None,
      to_date: Optional[str] = None,
      periodicity: Optional[str] = "Yearly"
  ) -> str:
      """
      Get standard financial reports (P&L, Balance Sheet, Cash Flow).
      
      Args:
          report_type: Type of financial statement 
                     ('Profit and Loss Statement', 'Balance Sheet', 'Cash Flow')
          company: Company name
          from_date: Start date (YYYY-MM-DD format, optional)
          to_date: End date (YYYY-MM-DD format, optional) 
          periodicity: Periodicity (Monthly, Quarterly, Half-Yearly, Yearly)
      """
      try:
          client = get_client()
          
          # Build filters for financial report
          filters = {
              "company": company,
              "periodicity": periodicity
          }
          
          if from_date:
              filters["from_date"] = from_date
          if to_date:
              filters["to_date"] = to_date
          
          # Prepare request data
          request_data = {
              "cmd": "frappe.desk.query_report.run",
              "report_name": report_type,
              "filters": json.dumps(filters),
              "ignore_prepared_report": 1
          }
          
          # Run the financial report
          response = await client.post("api/method/frappe.desk.query_report.run", json_data=request_data)
          
          if "message" in response:
              result = response["message"]
              
              formatted_result = {
                  "report_type": report_type,
                  "company": company,
                  "filters": filters,
                  "columns": result.get("columns", []),
                  "data": result.get("result", [])
              }
              
              return json.dumps(formatted_result, indent=2)
          else:
              return json.dumps(response, indent=2)
              
      except Exception as error:
          return _format_error_response(error, "get_financial_statements")

• src/server.py:39-42 (registration)

  Registers the reports module tools (including get_financial_statements) with the MCP server instance.

  helpers.register_tools(mcp)
  documents.register_tools(mcp)
  schema.register_tools(mcp)
  reports.register_tools(mcp)

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

  Helper function used by get_financial_statements (and other report tools) to format error responses.

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