HVManager

A Model Context Protocol (MCP) server that gives AI agents full control of Hyper-V.

Create, clone, and configure virtual machines; drive their screen and keyboard; read the screen with OCR; manage disks, ISOs, checkpoints and networking — and convert VMs and disk images to and from the QEMU/libvirt and Proxmox VE ecosystems. 58 tools, all over a single MCP endpoint.

---

Why

Hyper-V is scriptable through PowerShell, but that's awkward for an AI agent to drive directly: every call needs elevation, output isn't structured, and there's no clean way to "look at the screen" or "press a key". HVManager wraps all of that behind a typed MCP tool surface so an assistant can operate VMs the way a person would — boot one, watch it, type into it, snapshot it, move it to another hypervisor — without ever opening the Hyper-V GUI.

Highlights

• Full VM lifecycle — create, clone, start/stop/save/resume, rename, delete, export/import.
• Screen & input — screenshot (PNG/base64), OCR text extraction, keystrokes, scancodes, key combos, and synthetic mouse control.
• Storage & networking — VHD/VHDX create/resize/attach, ISO mounting, virtual switches, VLANs, guest IP discovery.
• Checkpoints — create, list, restore, and remove snapshots.
• Cross-hypervisor conversion — move disks and whole VMs between Hyper-V and QEMU/libvirt / Proxmox VE, powered by qemu-img (auto-downloaded if you don't have it).
• Zero-UAC operation — an optional one-time setup runs the server elevated via a hidden scheduled task, so the agent never triggers a consent prompt.

Requirements

• Windows 10/11 Pro/Enterprise or Windows Server with the Hyper-V role enabled
• Python 3.10+
• PowerShell (ships with Windows)
• Administrator rights for most operations (see Elevation)
• Optional: Tesseract OCR for vm_ocr
• Optional: qemu-img for conversions — auto-downloaded on demand if missing

Installation

git clone https://github.com/jr551/hvmanager.git
cd hvmanager
pip install -e .

Elevation (zero UAC)

Hyper-V cmdlets require elevation. You have two options:

Recommended — one-time setup (no more UAC prompts):

# In an Administrator PowerShell:
python setup_elevated.py

This registers a Windows scheduled task that runs the server elevated and windowless (via pythonw.exe, so no console floats on your desktop), listening on http://127.0.0.1:9023. The unprivileged launcher then bridges stdio to it — the agent connects normally and never sees a consent prompt.

Or run directly (requires launching your MCP client as Administrator).

MCP client configuration

After running setup_elevated.py (recommended):

{
  "mcpServers": {
    "hyperv": {
      "command": "python",
      "args": ["-m", "hvmanager.launcher"]
    }
  }
}

Without the elevated task (run your client as Administrator):

{
  "mcpServers": {
    "hyperv": {
      "command": "python",
      "args": ["-m", "hvmanager.server"]
    }
  }
}

The elevated server also speaks SSE directly at http://127.0.0.1:9023/sse if your client prefers HTTP.

Tool catalog (58 tools)

VM discovery & lifecycle

Tool	Description
vm_list	List all VMs with basic info
vm_get	Detailed VM info (disks, network, checkpoints)
vm_create	Create a VM with disk, network, ISO
vm_clone	Clone an existing VM
vm_delete	Delete a VM (optionally its files)
vm_start / vm_stop / vm_restart	Power control
vm_save / vm_resume	Suspend / resume
vm_rename	Rename a VM
vm_export / vm_import	Export to / import from a folder

Configuration

Tool	Description
vm_get_config / vm_set_config	Inspect / edit memory, CPU, Secure Boot, TPM, autostart, boot order, …
vm_get_firmware / vm_set_boot_order	Firmware & boot order (Gen 2)
vm_set_automatic_checkpoint	Toggle automatic checkpoints

Screen, input & OCR

Tool	Description
vm_screenshot	Capture the display (base64 PNG)
vm_save_screenshot	Capture and save a PNG to disk
vm_ocr	Extract on-screen text via OCR
vm_send_keys / vm_type_text	Type text (with {key} escapes)
vm_send_scancodes / vm_send_scancodes_delayed	Raw scancodes
vm_send_key_combo / vm_press_key	Combos (Ctrl+C, …) and named keys
vm_mouse_move / vm_mouse_click	Synthetic mouse

Storage, ISO & networking

Tool	Description
disk_create / disk_resize / disk_list	Manage VHD/VHDX files
vm_add_disk / vm_remove_disk	Attach / detach disks
vm_mount_iso / vm_unmount_iso / vm_list_isos	DVD/ISO management
vm_set_network / vm_add_network_adapter	Connect adapters to switches
vm_set_vlan / vm_get_ip	VLAN tagging / guest IP
switch_list	List virtual switches

Checkpoints, metrics & host

Tool	Description
vm_create_checkpoint / vm_list_checkpoints / vm_restore_checkpoint / vm_remove_checkpoint	Snapshots
vm_metrics	CPU/memory/disk/network usage (resource metering)
vm_integration_services	Integration service status
vm_copy_file	Copy a file host → guest
vm_connect	Launch the VMConnect GUI
host_info	Hyper-V host info

QEMU / Proxmox conversion

Tool	Description
convert_check	Check/auto-fetch qemu-img and report its version
disk_image_info	Inspect any disk image (vhdx/vhd/qcow2/raw/vmdk/vdi)
disk_convert	Convert a disk image between formats (VHDX ⇄ qcow2/raw/vmdk/vdi)
vm_export_qemu	Export a VM to QEMU/libvirt (converts disks + writes a domain XML and launch script)
vm_export_proxmox	Export a VM for Proxmox VE (converts disks + writes a qm import script)
vm_import_image	Import a qcow2/raw/vmdk/vdi image as a new Hyper-V VM
vm_import_proxmox	Import a Proxmox disk + .conf as a new Hyper-V VM (derives memory/cores/BIOS)

Cross-hypervisor conversion

HVManager bridges Hyper-V (VHD/VHDX) with the QEMU/libvirt and Proxmox VE worlds. Disk conversion is performed by qemu-img — and you don't have to install it: if no system qemu-img is found, a small portable build (~3.6 MB) is downloaded to a temp cache on first use and reused thereafter.

• Export to QEMU (vm_export_qemu) — converts the VM's disks (default qcow2) and writes a ready-to-define libvirt domain XML plus a qemu-system launch script.
• Export to Proxmox (vm_export_proxmox) — converts disks and writes an import-<vmid>.sh that runs qm create + qm importdisk on a Proxmox node.
• Import (vm_import_image, vm_import_proxmox) — converts a foreign image to VHDX and wraps a new Hyper-V VM around it. Gen 2 imports disable Secure Boot by default for compatibility with non-Microsoft images; Proxmox imports derive memory/cores/BIOS from the VM's .conf.

To use your own qemu-img, put qemu-img.exe on PATH (or in C:\Program Files\qemu); it takes precedence over the download. Environment variables:

Variable	Effect
HVMANAGER_QEMU_IMG_URL	Override the portable-build download URL (pin a version / mirror)
HVMANAGER_QEMU_NO_DOWNLOAD=1	Disable auto-download (require a system install)

OCR

vm_ocr screenshots the VM and extracts visible text — handy when your model can't view images, or to read terminal/log output. Requires Tesseract.

{ "vm_name": "Kubuntu", "language": "eng", "width": 1920, "height": 1080 }

Returns the extracted text plus word positions and confidence scores. Language codes depend on installed Tesseract data (eng, deu, fra, spa, chi_sim, jpn, kor, …).

Scancode quick reference

Key	Code	Key	Code	Key	Code
Enter	28	Tab	15	Ctrl	29
Space	57	Backspace	14	Alt	56
Escape	1	Delete	83	Shift	42
←	75	→	77	Windows	91
↑	72	↓	80	F1–F12	59–70

Prefer vm_send_key_combo / vm_press_key / vm_type_text over raw scancodes where possible.

Architecture

File	Role
hyperv.py	PowerShell/WMI wrapper for all Hyper-V operations
convert.py	qemu-img-backed disk/VM conversion to and from QEMU & Proxmox
server.py	FastMCP server exposing the 58 tools
launcher.py	Bridges stdio to the elevated SSE server (zero UAC)
setup_elevated.py	One-time scheduled-task setup for permanent, windowless elevation

Every Hyper-V call shells out to PowerShell with CREATE_NO_WINDOW, and child processes run hidden so nothing flashes on screen during automation.

Building a package

pip install build
python -m build        # produces dist/*.whl and dist/*.tar.gz

CI (.github/workflows/ci.yml) runs the test suite and builds the package on every push; tagged releases attach the built wheel and sdist as release assets.

Development

pip install -e .
python -m pytest        # unit tests run with no Hyper-V host required

The test suite monkeypatches the PowerShell/qemu-img layer, so it runs anywhere — no host, no elevation, no qemu-img needed.

License

HVManager is licensed under the GNU Affero General Public License v3.0 (LICENSE).

• Personal & non-commercial use is free.
• Commercial use is permitted, but the AGPL is strong copyleft: if you build on HVManager — including offering it (or a derivative) as a network/hosted service — you must release the complete corresponding source of your application under the AGPL.
• Don't want the copyleft obligation? A separate commercial license is available that lets you use HVManager in closed-source products. See LICENSING.md.

By contributing, you agree your contributions are licensed under the same terms.

Disclaimer

HVManager automates a hypervisor and can create, modify, and delete virtual machines and their disks. Use it against systems you own or are authorized to manage, and keep backups of anything you care about. Provided "as is", without warranty of any kind.