apply_formula

Instructions

Apply Excel formula to cell.

Args:
    session_id: Session ID from open_workbook (required)
    sheet_name: Name of worksheet
    cell: Cell address (e.g., "A1")
    formula: Excel formula to apply

Implementation Reference

• src/xlwings_mcp/xlwings_impl/calculations_xlw.py:15-78 (handler)

  Core implementation of the apply_formula tool logic for session-based workbook using xlwings. Applies formula to specified cell, normalizes it, calculates result, saves workbook, and returns detailed response.

  def apply_formula_xlw_with_wb(
      wb,
      sheet_name: str,
      cell: str,
      formula: str
  ) -> Dict[str, Any]:
      """Apply formula using existing workbook object (session-based).
      
      Args:
          wb: Workbook object from session
          sheet_name: Sheet name
          cell: Target cell (e.g., A1)
          formula: Formula to apply
          
      Returns:
          Dictionary with result and calculated value
      """
      try:
          # Check sheet exists
          if sheet_name not in [s.name for s in wb.sheets]:
              return {"error": f"Sheet '{sheet_name}' not found"}
          
          ws = wb.sheets[sheet_name]
          
          # Normalize formula
          if not formula.startswith('='):
              formula = f'={formula}'
          
          # Get cell
          cell_range = ws.range(cell)
          
          # Apply formula
          try:
              cell_range.formula = formula
          except Exception as e:
              return {
                  "error": f"Formula error in cell {cell}: {str(e)}",
                  "formula": formula,
                  "cell": cell
              }
          
          # Get calculated result
          try:
              calculated_value = cell_range.value
              display_value = cell_range.api.Text
          except Exception as e:
              logger.warning(f"Failed to read calculated value: {e}")
              calculated_value = None
              display_value = None
          
          # Save workbook
          wb.save()
          
          return {
              "message": f"Formula applied to {cell}",
              "cell": cell,
              "formula": formula,
              "calculated_value": calculated_value,
              "display_value": display_value
          }
          
      except Exception as e:
          logger.error(f"Failed to apply formula: {e}")
          return {"error": f"Failed to apply formula: {str(e)}"}

• src/xlwings_mcp/server.py:232-265 (registration)

  MCP tool registration using @mcp.tool() decorator. Defines input schema via parameters and docstring, validates session, calls the handler, and handles errors.

  @mcp.tool()
  def apply_formula(
      session_id: str,
      sheet_name: str,
      cell: str,
      formula: str
  ) -> str:
      """
      Apply Excel formula to cell.
      
      Args:
          session_id: Session ID from open_workbook (required)
          sheet_name: Name of worksheet
          cell: Cell address (e.g., "A1")
          formula: Excel formula to apply
      """
      try:
          # Validate session using centralized helper
          session = get_validated_session(session_id)
          if isinstance(session, str):  # Error message returned
              return session
          
          with session.lock:
              from xlwings_mcp.xlwings_impl.calculations_xlw import apply_formula_xlw_with_wb
              result = apply_formula_xlw_with_wb(session.workbook, sheet_name, cell, formula)
          
          return result.get("message", "Formula applied successfully") if "error" not in result else f"Error: {result['error']}"
              
      except (ValidationError, CalculationError) as e:
          return f"Error: {str(e)}"
      except Exception as e:
          logger.error(f"Error applying formula: {e}")
          raise