Excel MCP Server

Instructions

Implementation Reference

• src/excel_mcp/server.py:444-455 (handler)

  MCP tool handler and registration for 'merge_cells'. The @mcp.tool() decorator registers this function as an MCP tool. It handles input validation via type hints, calls the helper function, and returns success/error messages.

  @mcp.tool()
  def merge_cells(filepath: str, sheet_name: str, start_cell: str, end_cell: str) -> str:
      """Merge a range of cells."""
      try:
          full_path = get_excel_path(filepath)
          result = merge_range(full_path, sheet_name, start_cell, end_cell)
          return result["message"]
      except (ValidationError, SheetError) as e:
          return f"Error: {str(e)}"
      except Exception as e:
          logger.error(f"Error merging cells: {e}")
          raise

• src/excel_mcp/sheet.py:189-211 (helper)

  Supporting utility function that performs the actual cell merging using openpyxl. Parses the cell range, calls worksheet.merge_cells(), saves the workbook, and returns a success message.

  def merge_range(filepath: str, sheet_name: str, start_cell: str, end_cell: str) -> Dict[str, Any]:
      """Merge a range of cells."""
      try:
          wb = load_workbook(filepath)
          if sheet_name not in wb.sheetnames:
              raise SheetError(f"Sheet '{sheet_name}' not found")
              
          start_row, start_col, end_row, end_col = parse_cell_range(start_cell, end_cell)
  
          if end_row is None or end_col is None:
              raise SheetError("Both start and end cells must be specified for merging")
  
          range_string = format_range_string(start_row, start_col, end_row, end_col)
          worksheet = wb[sheet_name]
          worksheet.merge_cells(range_string)
          wb.save(filepath)
          return {"message": f"Range '{range_string}' merged in sheet '{sheet_name}'"}
      except SheetError as e:
          logger.error(str(e))
          raise
      except Exception as e:
          logger.error(f"Failed to merge range: {e}")
          raise SheetError(str(e))