xlwings Excel MCP Server

Instructions

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
• src/xlwings_mcp/xlwings_impl/rows_cols_xlw.py:88-167 (handler)

  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()
• src/xlwings_mcp/xlwings_impl/rows_cols_xlw.py:368-426 (handler)

  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)}