xlwings Excel MCP Server

Instructions

Implementation Reference

• src/xlwings_mcp/server.py:1179-1244 (handler)

  MCP tool registration and handler function for 'delete_range'. Dispatches to session-based or legacy filepath-based implementations.
  @mcp.tool() def delete_range( sheet_name: str, start_cell: str, end_cell: str, session_id: Optional[str] = None, filepath: Optional[str] = None, shift_direction: str = "up" ) -> str: """ Delete a range of cells and shift remaining cells. Args: sheet_name: Name of worksheet start_cell: Starting cell end_cell: Ending cell session_id: Session ID from open_workbook (preferred) filepath: Path to Excel file (legacy, deprecated) shift_direction: Direction to shift cells ("up" or "left") Note: Use session_id for better performance. filepath parameter is deprecated. """ try: # Support both new (session_id) and old (filepath) API if session_id: # New API: use session session = SESSION_MANAGER.get_session(session_id) if not session: return ERROR_TEMPLATES['SESSION_NOT_FOUND'].format( session_id=session_id, ttl=10 # Default TTL is 10 minutes (600 seconds) ) with session.lock: from xlwings_mcp.xlwings_impl.range_xlw import delete_range_xlw_with_wb result = delete_range_xlw_with_wb( session.workbook, sheet_name, start_cell, end_cell, shift_direction ) elif filepath: # Legacy API: backwards compatibility logger.warning("Using deprecated filepath parameter. Please use session_id instead.") full_path = get_excel_path(filepath) from xlwings_mcp.xlwings_impl.range_xlw import delete_range_xlw result = delete_range_xlw( full_path, sheet_name, start_cell, end_cell, shift_direction ) else: return ERROR_TEMPLATES['PARAMETER_MISSING'].format( param1='session_id', param2='filepath' ) return result.get("message", "Range deleted successfully") if "error" not in result else f"Error: {result['error']}" except (ValidationError, SheetError) as e: return f"Error: {str(e)}" except Exception as e: logger.error(f"Error deleting range: {e}") raise
• src/xlwings_mcp/xlwings_impl/range_xlw.py:367-446 (helper)

  Core implementation of delete_range using xlwings for legacy filepath mode. Opens workbook, deletes range with shift, saves and closes.
  def delete_range_xlw( filepath: str, sheet_name: str, start_cell: str, end_cell: str, shift_direction: str = "up" ) -> Dict[str, Any]: """ Delete a range of cells and shift remaining cells using xlwings. Args: filepath: Path to Excel file sheet_name: Name of worksheet start_cell: Top-left cell of range to delete end_cell: Bottom-right cell of range to delete shift_direction: Direction to shift cells ("up" or "left") Returns: Dict with success message or error """ app = None wb = None # Initialize COM for thread safety (Windows) _com_initialize() try: logger.info(f"Deleting range {start_cell}:{end_cell} in {sheet_name}, shift {shift_direction}") # Validate shift direction if shift_direction not in ["up", "left"]: return {"error": f"Invalid shift direction: {shift_direction}. Must be 'up' or 'left'"} # Check if file exists if not os.path.exists(filepath): return {"error": f"File not found: {filepath}"} # Open Excel app and workbook app = xw.App(visible=False, add_book=False) wb = app.books.open(filepath) # Check if sheet exists sheet_names = [s.name for s in wb.sheets] if sheet_name not in sheet_names: return {"error": f"Sheet '{sheet_name}' not found"} sheet = wb.sheets[sheet_name] # Get the range to delete delete_range = sheet.range(f"{start_cell}:{end_cell}") # Delete and shift cells if shift_direction == "up": # Shift cells up (xlShiftUp = -4162) delete_range.api.Delete(Shift=-4162) else: # shift_direction == "left" # Shift cells left (xlShiftToLeft = -4159) delete_range.api.Delete(Shift=-4159) # Save the workbook wb.save() logger.info(f"✅ Successfully deleted range {start_cell}:{end_cell}") return { "message": f"Successfully deleted range {start_cell}:{end_cell} and shifted cells {shift_direction}", "deleted_range": f"{start_cell}:{end_cell}", "shift_direction": shift_direction, "sheet": sheet_name } except Exception as e: logger.error(f"❌ Error deleting range: {str(e)}") return {"error": str(e)} finally: if wb: wb.close() if app: app.quit()
• src/xlwings_mcp/xlwings_impl/range_xlw.py:820-879 (helper)

  Session-based implementation of delete_range using existing workbook object from MCP session manager.
  def delete_range_xlw_with_wb( wb, sheet_name: str, start_cell: str, end_cell: str, shift_direction: str = "up" ) -> Dict[str, Any]: """ Session-based range deletion using existing workbook object. Args: wb: Workbook object from session sheet_name: Name of worksheet start_cell: Top-left cell of range to delete end_cell: Bottom-right cell of range to delete shift_direction: Direction to shift cells ("up" or "left") Returns: Dict with success message or error """ try: logger.info(f"🗑️ Deleting range {start_cell}:{end_cell} in {sheet_name}, shift {shift_direction}") # Validate shift direction if shift_direction not in ["up", "left"]: return {"error": f"Invalid shift direction: {shift_direction}. Must be 'up' or 'left'"} # Check if sheet exists sheet_names = [s.name for s in wb.sheets] if sheet_name not in sheet_names: return {"error": f"Sheet '{sheet_name}' not found"} sheet = wb.sheets[sheet_name] # Get the range to delete delete_range = sheet.range(f"{start_cell}:{end_cell}") # Delete and shift cells if shift_direction == "up": # Shift cells up (xlShiftUp = -4162) delete_range.api.Delete(Shift=-4162) else: # shift_direction == "left" # Shift cells left (xlShiftToLeft = -4159) delete_range.api.Delete(Shift=-4159) # Save the workbook wb.save() logger.info(f"✅ Successfully deleted range {start_cell}:{end_cell}") return { "message": f"Successfully deleted range {start_cell}:{end_cell} and shifted cells {shift_direction}", "deleted_range": f"{start_cell}:{end_cell}", "shift_direction": shift_direction, "sheet": sheet_name } except Exception as e: logger.error(f"❌ Error deleting range: {str(e)}") return {"error": str(e)}