insert_rows
Add rows to Excel worksheets at specified positions to organize data and create space for new entries in workbooks managed by the xlwings Excel MCP Server.
Instructions
Insert one or more rows starting at the specified row.
Args:
sheet_name: Name of worksheet
start_row: Row number to start inserting at
session_id: Session ID from open_workbook (preferred)
filepath: Path to Excel file (legacy, deprecated)
count: Number of rows 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_row | 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:1360-1413 (registration)Registration of the 'insert_rows' tool using @mcp.tool(). This wrapper handles session-based and legacy filepath modes by calling the appropriate implementation functions.
def insert_rows( sheet_name: str, start_row: int, session_id: Optional[str] = None, filepath: Optional[str] = None, count: int = 1 ) -> str: """ Insert one or more rows starting at the specified row. Args: sheet_name: Name of worksheet start_row: Row number to start inserting at session_id: Session ID from open_workbook (preferred) filepath: Path to Excel file (legacy, deprecated) count: Number of rows 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_rows_xlw_with_wb result = insert_rows_xlw_with_wb(session.workbook, sheet_name, start_row, 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_rows_xlw result = insert_rows_xlw(full_path, sheet_name, start_row, 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 rows: {e}") raise - Core handler function that executes the row insertion logic using xlwings for filepath-based operations. Opens workbook, inserts rows via COM API, saves, and cleans up.
def insert_rows_xlw( filepath: str, sheet_name: str, start_row: int, count: int = 1 ) -> Dict[str, Any]: """ Insert one or more rows in Excel using xlwings. Args: filepath: Path to Excel file sheet_name: Name of worksheet start_row: Row number to start insertion (1-based) count: Number of rows 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} rows at row {start_row} 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] # Insert rows using xlwings # Get the range for the row to insert at target_row = sheet.range(f"{start_row}:{start_row}") # Insert rows - use COM API for better control for _ in range(count): target_row.api.Insert() # Save the workbook wb.save() logger.info(f"✅ Successfully inserted {count} rows at row {start_row}") return { "message": f"Successfully inserted {count} rows at row {start_row}", "sheet": sheet_name, "start_row": start_row, "count": count } except Exception as e: logger.error(f"Error inserting rows: {e}") return {"error": str(e)} finally: if wb: wb.close() if app: app.quit() - Helper function for session-based row insertion using pre-opened workbook object. Used by the main tool wrapper when session_id is provided.
def insert_rows_xlw_with_wb( wb, sheet_name: str, start_row: 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_row: Row number to start insertion (1-based) count: Number of rows to insert Returns: Dict with success message or error """ try: logger.info(f"📊 Inserting {count} rows at row {start_row} 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] # Insert rows using xlwings # Get the range for the row to insert at target_row = sheet.range(f"{start_row}:{start_row}") # Insert rows - use COM API for better control for _ in range(count): target_row.api.Insert() # Save the workbook wb.save() logger.info(f"✅ Successfully inserted {count} rows at row {start_row}") return { "message": f"Successfully inserted {count} rows at row {start_row}", "sheet": sheet_name, "start_row": start_row, "count": count } except Exception as e: logger.error(f"Error inserting rows: {e}") return {"error": str(e)}