Excel MCP Server

Instructions

Implementation Reference

• src/excel_mcp/server.py:510-534 (handler)

  MCP tool handler for 'delete_range' that validates input, resolves file path, calls the sheet operation, and returns the result message or error.

  @mcp.tool()
  def delete_range(
      filepath: str,
      sheet_name: str,
      start_cell: str,
      end_cell: str,
      shift_direction: str = "up"
  ) -> str:
      """Delete a range of cells and shift remaining cells."""
      try:
          full_path = get_excel_path(filepath)
          from excel_mcp.sheet import delete_range_operation
          result = delete_range_operation(
              full_path,
              sheet_name,
              start_cell,
              end_cell,
              shift_direction
          )
          return result["message"]
      except (ValidationError, SheetError) as e:
          return f"Error: {str(e)}"
      except Exception as e:
          logger.error(f"Error deleting range: {e}")
          raise

• src/excel_mcp/sheet.py:315-368 (handler)

  Core implementation of delete_range operation: loads workbook, validates sheet and range, clears cell contents/formatting using helper, shifts rows/columns, saves workbook.

  def delete_range_operation(
      filepath: str,
      sheet_name: str,
      start_cell: str,
      end_cell: Optional[str] = None,
      shift_direction: str = "up"
  ) -> Dict[str, Any]:
      """Delete a range of cells and shift remaining cells."""
      try:
          wb = load_workbook(filepath)
          if sheet_name not in wb.sheetnames:
              raise SheetError(f"Sheet '{sheet_name}' not found")
              
          worksheet = wb[sheet_name]
          
          # Validate range
          try:
              start_row, start_col, end_row, end_col = parse_cell_range(start_cell, end_cell)
              if end_row and end_row > worksheet.max_row:
                  raise SheetError(f"End row {end_row} out of bounds (1-{worksheet.max_row})")
              if end_col and end_col > worksheet.max_column:
                  raise SheetError(f"End column {end_col} out of bounds (1-{worksheet.max_column})")
          except ValueError as e:
              raise SheetError(f"Invalid range: {str(e)}")
              
          # Validate shift direction
          if shift_direction not in ["up", "left"]:
              raise ValidationError(f"Invalid shift direction: {shift_direction}. Must be 'up' or 'left'")
              
          range_string = format_range_string(
              start_row, start_col,
              end_row or start_row,
              end_col or start_col
          )
          
          # Delete range contents
          delete_range(worksheet, start_cell, end_cell)
          
          # Shift cells if needed
          if shift_direction == "up":
              worksheet.delete_rows(start_row, (end_row or start_row) - start_row + 1)
          elif shift_direction == "left":
              worksheet.delete_cols(start_col, (end_col or start_col) - start_col + 1)
              
          wb.save(filepath)
          
          return {"message": f"Range {range_string} deleted successfully"}
      except (ValidationError, SheetError) as e:
          logger.error(str(e))
          raise
      except Exception as e:
          logger.error(f"Failed to delete range: {e}")
          raise SheetError(str(e))

• src/excel_mcp/sheet.py:171-188 (helper)

  Helper function to clear contents, formatting, font, border, fill, number format, and alignment from a range of cells.

  def delete_range(worksheet: Worksheet, start_cell: str, end_cell: Optional[str] = None) -> None:
      """Delete contents and formatting of a range."""
      start_row, start_col, end_row, end_col = parse_cell_range(start_cell, end_cell)
  
      if end_row is None:
          end_row = start_row
          end_col = start_col
  
      for row in range(start_row, end_row + 1):
          for col in range(start_col, end_col + 1):
              cell = worksheet.cell(row=row, column=col)
              cell.value = None
              cell.font = Font()
              cell.border = Border()
              cell.fill = PatternFill()
              cell.number_format = "General"
              cell.alignment = None