Excel Finance MCP

Instructions

Implementation Reference

• src/tools/financial-tools.ts:247-277 (handler)

  Tool definition including name, description, input schema, and handler function that dynamically calls the appropriate Python RatioAnalysis method based on ratioType.
  { name: "calculate_financial_ratios", description: "Calculate comprehensive financial ratios", inputSchema: { type: "object", properties: { ratioType: { type: "string", enum: ["current_ratio", "quick_ratio", "debt_to_equity", "return_on_assets", "return_on_equity", "gross_margin", "operating_margin", "net_margin", "inventory_turnover", "asset_turnover"] }, values: { type: "object", description: "Financial values needed for calculation" } }, required: ["ratioType", "values"] }, handler: async (args: any): Promise<ToolResult> => { try { const result = await pythonBridge.callPythonFunction({ module: 'financial_calculations', function: `RatioAnalysis.${args.ratioType}`, args: Object.values(args.values) }); return result; } catch (error) { return { success: false, error: error instanceof Error ? error.message : String(error) }; } } },
• src/tools/financial-tools.ts:250-260 (schema)

  Input schema defining the expected arguments: ratioType (enum of supported ratios) and values (object of financial data).
  inputSchema: { type: "object", properties: { ratioType: { type: "string", enum: ["current_ratio", "quick_ratio", "debt_to_equity", "return_on_assets", "return_on_equity", "gross_margin", "operating_margin", "net_margin", "inventory_turnover", "asset_turnover"] }, values: { type: "object", description: "Financial values needed for calculation" } }, required: ["ratioType", "values"]
• src/index.ts:32-44 (registration)

  Registers the financialTools (including calculate_financial_ratios) by spreading into the allTools array used for tool listing and execution.
  const allTools = [ ...excelTools, ...financialTools, ...rentalTools, ...expenseTools, ...reportingTools, ...cashFlowTools, ...taxTools, ...analyticsTools, ...chartTools, ...complianceTools, ...propertyTools, ];
• src/index.ts:46-52 (registration)

  MCP ListTools handler that exposes calculate_financial_ratios in the tools list.
  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: allTools.map(tool => ({ name: tool.name, description: tool.description, inputSchema: tool.inputSchema, })), }));
• src/python/financial_calculations.py:226-288 (helper)

  Python helper class with static methods implementing each financial ratio calculation (current_ratio, quick_ratio, etc.), invoked dynamically by the TS handler.
  class RatioAnalysis: """Financial ratio analysis for accounting""" @staticmethod def current_ratio(current_assets: float, current_liabilities: float) -> float: """Calculate current ratio""" return current_assets / current_liabilities if current_liabilities != 0 else float('inf') @staticmethod def quick_ratio(current_assets: float, inventory: float, current_liabilities: float) -> float: """Calculate quick ratio (acid test)""" return (current_assets - inventory) / current_liabilities if current_liabilities != 0 else float('inf') @staticmethod def debt_to_equity(total_debt: float, total_equity: float) -> float: """Calculate debt-to-equity ratio""" return total_debt / total_equity if total_equity != 0 else float('inf') @staticmethod def return_on_assets(net_income: float, total_assets: float) -> float: """Calculate ROA""" return net_income / total_assets if total_assets != 0 else 0 @staticmethod def return_on_equity(net_income: float, shareholders_equity: float) -> float: """Calculate ROE""" return net_income / shareholders_equity if shareholders_equity != 0 else 0 @staticmethod def gross_margin(revenue: float, cogs: float) -> float: """Calculate gross margin percentage""" return ((revenue - cogs) / revenue * 100) if revenue != 0 else 0 @staticmethod def operating_margin(operating_income: float, revenue: float) -> float: """Calculate operating margin percentage""" return (operating_income / revenue * 100) if revenue != 0 else 0 @staticmethod def net_margin(net_income: float, revenue: float) -> float: """Calculate net profit margin percentage""" return (net_income / revenue * 100) if revenue != 0 else 0 @staticmethod def inventory_turnover(cogs: float, average_inventory: float) -> float: """Calculate inventory turnover ratio""" return cogs / average_inventory if average_inventory != 0 else 0 @staticmethod def days_sales_outstanding(accounts_receivable: float, annual_sales: float) -> float: """Calculate DSO""" return (accounts_receivable / annual_sales * 365) if annual_sales != 0 else 0 @staticmethod def asset_turnover(revenue: float, average_total_assets: float) -> float: """Calculate asset turnover ratio""" return revenue / average_total_assets if average_total_assets != 0 else 0 @staticmethod def interest_coverage(ebit: float, interest_expense: float) -> float: """Calculate interest coverage ratio""" return ebit / interest_expense if interest_expense != 0 else float('inf')