insert_columns
Insert columns into Excel worksheets to reorganize data structure. Specify sheet name, starting column position, and number of columns to add for spreadsheet modification.
Instructions
Insert one or more columns starting at the specified column.
Args:
sheet_name: Name of worksheet
start_col: Column number to start inserting at
session_id: Session ID from open_workbook (preferred)
filepath: Path to Excel file (legacy, deprecated)
count: Number of columns to insert
Note: Use session_id for better performance. filepath parameter is deprecated.Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sheet_name | Yes | ||
| start_col | Yes | ||
| session_id | No | ||
| filepath | No | ||
| count | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/xlwings_mcp/server.py:1415-1469 (registration)Registration of the 'insert_columns' tool using @mcp.tool() decorator. Dispatches to session-based or legacy filepath-based handlers.
@mcp.tool() def insert_columns( sheet_name: str, start_col: int, session_id: Optional[str] = None, filepath: Optional[str] = None, count: int = 1 ) -> str: """ Insert one or more columns starting at the specified column. Args: sheet_name: Name of worksheet start_col: Column number to start inserting at session_id: Session ID from open_workbook (preferred) filepath: Path to Excel file (legacy, deprecated) count: Number of columns to insert 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.rows_cols_xlw import insert_columns_xlw_with_wb result = insert_columns_xlw_with_wb(session.workbook, sheet_name, start_col, count) 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.rows_cols_xlw import insert_columns_xlw result = insert_columns_xlw(full_path, sheet_name, start_col, count) else: return ERROR_TEMPLATES['PARAMETER_MISSING'].format( param1='session_id', param2='filepath' ) if "error" in result: return f"Error: {result['error']}" return result["message"] except (ValidationError, SheetError) as e: return f"Error: {str(e)}" except Exception as e: logger.error(f"Error inserting columns: {e}") raise - Stateless handler implementation for inserting columns using xlwings with filepath. Handles file opening, sheet access, column insertion via COM API, and cleanup.
def insert_columns_xlw( filepath: str, sheet_name: str, start_col: int, count: int = 1 ) -> Dict[str, Any]: """ Insert one or more columns in Excel using xlwings. Args: filepath: Path to Excel file sheet_name: Name of worksheet start_col: Column number to start insertion (1-based) count: Number of columns to insert Returns: Dict with success message or error """ app = None wb = None # Initialize COM for thread safety (Windows) _com_initialize() try: logger.info(f"Inserting {count} columns at column {start_col} 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] # Convert column number to letter def col_num_to_letter(n): string = "" while n > 0: n, remainder = divmod(n - 1, 26) string = chr(65 + remainder) + string return string col_letter = col_num_to_letter(start_col) # Insert columns using xlwings target_col = sheet.range(f"{col_letter}:{col_letter}") # Insert columns - use COM API for better control for _ in range(count): target_col.api.Insert() # Save the workbook wb.save() logger.info(f"✅ Successfully inserted {count} columns at column {col_letter}") return { "message": f"Successfully inserted {count} columns at column {col_letter}", "sheet": sheet_name, "start_col": start_col, "count": count } except Exception as e: logger.error(f"Error inserting columns: {e}") return {"error": str(e)} finally: if wb: wb.close() if app: app.quit() - Stateful (session-based) handler implementation for inserting columns using an existing workbook object from session. Performs column insertion via COM API.
def insert_columns_xlw_with_wb( wb, sheet_name: str, start_col: int, count: int = 1 ) -> Dict[str, Any]: """Session-based version using existing workbook object. Args: wb: Workbook object from session sheet_name: Name of worksheet start_col: Column number to start insertion (1-based) count: Number of columns to insert Returns: Dict with success message or error """ try: logger.info(f"📊 Inserting {count} columns at column {start_col} 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] # Convert column number to letter def col_num_to_letter(n): string = "" while n > 0: n, remainder = divmod(n - 1, 26) string = chr(65 + remainder) + string return string col_letter = col_num_to_letter(start_col) # Insert columns using xlwings target_col = sheet.range(f"{col_letter}:{col_letter}") # Insert columns - use COM API for better control for _ in range(count): target_col.api.Insert() # Save the workbook wb.save() logger.info(f"✅ Successfully inserted {count} columns at column {col_letter}") return { "message": f"Successfully inserted {count} columns at column {col_letter}", "sheet": sheet_name, "start_col": start_col, "count": count } except Exception as e: logger.error(f"Error inserting columns: {e}") return {"error": str(e)}