Excel MCP Server

Instructions

Implementation Reference

• src/excel_mcp/server.py:482-509 (handler)

  MCP tool handler for 'copy_range': handles input parameters, resolves file path, imports and calls the core copy_range_operation function from sheet.py, and returns the result message or error.
  @mcp.tool() def copy_range( filepath: str, sheet_name: str, source_start: str, source_end: str, target_start: str, target_sheet: Optional[str] = None ) -> str: """Copy a range of cells to another location.""" try: full_path = get_excel_path(filepath) from excel_mcp.sheet import copy_range_operation result = copy_range_operation( full_path, sheet_name, source_start, source_end, target_start, target_sheet or sheet_name # Use source sheet if target_sheet is None ) return result["message"] except (ValidationError, SheetError) as e: return f"Error: {str(e)}" except Exception as e: logger.error(f"Error copying range: {e}") raise
• src/excel_mcp/sheet.py:261-314 (helper)

  Core helper function implementing the range copy logic: loads workbook, validates sheets and ranges, calculates offsets, copies cell values and styles cell-by-cell, and saves the workbook.
  def copy_range_operation( filepath: str, sheet_name: str, source_start: str, source_end: str, target_start: str, target_sheet: Optional[str] = None ) -> Dict: """Copy a range of cells to another location.""" try: wb = load_workbook(filepath) if sheet_name not in wb.sheetnames: logger.error(f"Sheet '{sheet_name}' not found") raise ValidationError(f"Sheet '{sheet_name}' not found") source_ws = wb[sheet_name] target_ws = wb[target_sheet] if target_sheet else source_ws # Parse source range try: start_row, start_col, end_row, end_col = parse_cell_range(source_start, source_end) except ValueError as e: logger.error(f"Invalid source range: {e}") raise ValidationError(f"Invalid source range: {str(e)}") # Parse target starting point try: target_row = int(''.join(filter(str.isdigit, target_start))) target_col = column_index_from_string(''.join(filter(str.isalpha, target_start))) except ValueError as e: logger.error(f"Invalid target cell: {e}") raise ValidationError(f"Invalid target cell: {str(e)}") # Copy the range row_offset = target_row - start_row col_offset = target_col - start_col for i in range(start_row, end_row + 1): for j in range(start_col, end_col + 1): source_cell = source_ws.cell(row=i, column=j) target_cell = target_ws.cell(row=i + row_offset, column=j + col_offset) target_cell.value = source_cell.value if source_cell.has_style: target_cell._style = copy(source_cell._style) wb.save(filepath) return {"message": f"Range copied successfully"} except (ValidationError, SheetError): raise except Exception as e: logger.error(f"Failed to copy range: {e}") raise SheetError(f"Failed to copy range: {str(e)}")
• src/excel_mcp/sheet.py:83-171 (helper)

  Supporting helper function for copying ranges between worksheets, including detailed style copying (font, border, fill, format, alignment). Not directly called by the tool but provides similar copy logic.
  def copy_range( source_ws: Worksheet, target_ws: Worksheet, source_range: str, target_start: Optional[str] = None, ) -> None: """Copy range from source worksheet to target worksheet.""" # Parse source range if ':' in source_range: source_start, source_end = source_range.split(':') else: source_start = source_range source_end = None src_start_row, src_start_col, src_end_row, src_end_col = parse_cell_range( source_start, source_end ) if src_end_row is None: src_end_row = src_start_row src_end_col = src_start_col if target_start is None: target_start = source_start tgt_start_row, tgt_start_col, _, _ = parse_cell_range(target_start) for i, row in enumerate(range(src_start_row, src_end_row + 1)): for j, col in enumerate(range(src_start_col, src_end_col + 1)): source_cell = source_ws.cell(row=row, column=col) target_cell = target_ws.cell(row=tgt_start_row + i, column=tgt_start_col + j) target_cell.value = source_cell.value try: # Copy font font_kwargs = {} if hasattr(source_cell.font, 'name'): font_kwargs['name'] = source_cell.font.name if hasattr(source_cell.font, 'size'): font_kwargs['size'] = source_cell.font.size if hasattr(source_cell.font, 'bold'): font_kwargs['bold'] = source_cell.font.bold if hasattr(source_cell.font, 'italic'): font_kwargs['italic'] = source_cell.font.italic if hasattr(source_cell.font, 'color'): font_color = None if source_cell.font.color: font_color = source_cell.font.color.rgb font_kwargs['color'] = font_color target_cell.font = Font(**font_kwargs) # Copy border new_border = Border() for side in ['left', 'right', 'top', 'bottom']: source_side = getattr(source_cell.border, side) if source_side and source_side.style: side_color = source_side.color.rgb if source_side.color else None setattr(new_border, side, Side( style=source_side.style, color=side_color )) target_cell.border = new_border # Copy fill if hasattr(source_cell, 'fill'): fill_kwargs = {'patternType': source_cell.fill.patternType} if hasattr(source_cell.fill, 'fgColor') and source_cell.fill.fgColor: fg_color = None if hasattr(source_cell.fill.fgColor, 'rgb'): fg_color = source_cell.fill.fgColor.rgb fill_kwargs['fgColor'] = fg_color if hasattr(source_cell.fill, 'bgColor') and source_cell.fill.bgColor: bg_color = None if hasattr(source_cell.fill.bgColor, 'rgb'): bg_color = source_cell.fill.bgColor.rgb fill_kwargs['bgColor'] = bg_color target_cell.fill = PatternFill(**fill_kwargs) # Copy number format and alignment if source_cell.number_format: target_cell.number_format = source_cell.number_format if source_cell.alignment: target_cell.alignment = source_cell.alignment except Exception: continue def delete_range(worksheet: Worksheet, start_cell: str, end_cell: Optional[str] = None) -> None: