unmerge_cells
Split merged Excel cells into individual cells to restore independent formatting and data entry. Specify the worksheet and cell range to separate previously combined cells.
Instructions
Unmerge a range of 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)
Note: Use session_id for better performance. filepath parameter is deprecated.Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sheet_name | Yes | ||
| start_cell | Yes | ||
| end_cell | Yes | ||
| session_id | No | ||
| filepath | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/xlwings_mcp/server.py:999-1051 (handler)MCP tool handler for 'unmerge_cells'. Dispatches to session-based or legacy filepath-based unmerge implementations in range_xlw.py.
@mcp.tool() def unmerge_cells( sheet_name: str, start_cell: str, end_cell: str, session_id: Optional[str] = None, filepath: Optional[str] = None ) -> str: """ Unmerge a range of 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) 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 unmerge_cells_xlw_with_wb result = unmerge_cells_xlw_with_wb(session.workbook, sheet_name, start_cell, end_cell) 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 unmerge_cells_xlw result = unmerge_cells_xlw(full_path, sheet_name, start_cell, end_cell) else: return ERROR_TEMPLATES['PARAMETER_MISSING'].format( param1='session_id', param2='filepath' ) return result.get("message", "Cells unmerged 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 unmerging cells: {e}") raise - Legacy filepath-based implementation of cell unmerging using xlwings. Opens workbook, checks range, unmerges, saves and closes.
def unmerge_cells_xlw(filepath: str, sheet_name: str, start_cell: str, end_cell: str) -> Dict[str, Any]: """ Unmerge cells in Excel using xlwings. Args: filepath: Path to Excel file sheet_name: Name of worksheet start_cell: Top-left cell of merge range end_cell: Bottom-right cell of merge range Returns: Dict with success message or error """ app = None wb = None # Initialize COM for thread safety (Windows) _com_initialize() try: logger.info(f"Unmerging cells {start_cell}:{end_cell} in {sheet_name}") # 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 unmerge unmerge_range = sheet.range(f"{start_cell}:{end_cell}") # Check if range is merged if not unmerge_range.merge_cells: return {"error": f"Range {start_cell}:{end_cell} is not merged"} # Unmerge the cells unmerge_range.unmerge() # Save the workbook wb.save() logger.info(f"✅ Successfully unmerged cells {start_cell}:{end_cell}") return { "message": f"Successfully unmerged cells {start_cell}:{end_cell}", "range": f"{start_cell}:{end_cell}", "sheet": sheet_name } except Exception as e: logger.error(f"❌ Error unmerging cells: {str(e)}") return {"error": str(e)} finally: if wb: wb.close() if app: app.quit() - Session-optimized variant of unmerge_cells that uses existing open workbook object for efficiency.
def unmerge_cells_xlw_with_wb(wb, sheet_name: str, start_cell: str, end_cell: str) -> Dict[str, Any]: """ Session-based cell unmerging using existing workbook object. Args: wb: Workbook object from session sheet_name: Name of worksheet start_cell: Top-left cell of merge range end_cell: Bottom-right cell of merge range Returns: Dict with success message or error """ try: logger.info(f"🔓 Unmerging cells {start_cell}:{end_cell} in {sheet_name}") # 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 unmerge unmerge_range = sheet.range(f"{start_cell}:{end_cell}") # Check if range is merged if not unmerge_range.merge_cells: return {"error": f"Range {start_cell}:{end_cell} is not merged"} # Unmerge the cells unmerge_range.unmerge() # Save the workbook wb.save() logger.info(f"✅ Successfully unmerged cells {start_cell}:{end_cell}") return { "message": f"Successfully unmerged cells {start_cell}:{end_cell}", "range": f"{start_cell}:{end_cell}", "sheet": sheet_name } except Exception as e: logger.error(f"❌ Error unmerging cells: {str(e)}") return {"error": str(e)} - src/xlwings_mcp/sheet.py:48-53 (helper)Higher-level wrapper around unmerge_cells_xlw in sheet.py module.
def unmerge_range(filepath: str, sheet_name: str, start_cell: str, end_cell: str) -> Dict[str, Any]: """Unmerge a range of cells.""" result = unmerge_cells_xlw(filepath, sheet_name, start_cell, end_cell) if "error" in result: raise SheetError(result["error"]) return result