desktop-hypervisor-mcp

Desktop Hypervisor MCP

One provider-neutral MCP server for the desktop hypervisors: VirtualBox, VMware Fusion, and VMware Workstation. Nine tools, ~1,800 context tokens, full coverage of what its two predecessor servers did in ~5,600.

It succeeds virtualbox-mcp-server (that history is preserved on the predecessor-virtualbox branch) and the never- released vmware-fusion-mcp-server, folding both into one capability-based surface.

Versioning note: stable releases of this server start at v2.0.0. The v1.x line (and its v1.0.0 release, kept for anyone still pinning it) belongs to the virtualbox-only predecessor; the 0.x tags were this server's pre-stable iterations. v2.0.0 is identical in content to v0.4.3, re-versioned as the stable line.

Design

• Capability-based, not lowest-common-denominator. Providers advertise what they can actually do (provider action=list): guest exec, OVA import/export, linked clones, pre-boot guestinfo injection, DHCP-lease IP discovery, ISO mastering… Unsupported operations fail by naming the missing capability, not with a provider error.
• Intent, not mechanism. "Ensure the cluster nodes share a network the host can reach" is expressible on both families; "create a host-only interface" is not. The neutral tools express intent; provider-native mechanism stays reachable, unabstracted, through execute_command.
• Artifacts resolve per provider. The same image name gives each hypervisor the artifact it can actually import — Talos's vmware-*.ova vs virtualbox-*.ova, Vagrant's vmware_desktop vs virtualbox boxes, Microsoft's per-hypervisor dev VM — keyed on (image, provider family, host arch).

Tools

Tool	Actions
provider	list — installed hypervisors with status, capabilities, formats, and remediation when not ready
artifact	catalog, resolve, fetch (dry_run) — verified downloads of official OS images, per provider
vm_lifecycle	create, start, stop, suspend, reset, delete, clone, import, export
vm_info	list, running, show, ip (in-guest tools, else DHCP leases by MAC — works for agentless guests like Talos)
vm_config	resources, nested_virt, attach_iso, guestinfo (pre-boot key/value injection, VMware)
snapshot	take, restore, delete, list (tree)
guest	exec, script, copy_in, copy_out, screenshot
network	ensure_cluster_network, expose_guest_port, make_iso, repack_iso
execute_command	raw VBoxManage / vmrun argv on the selected provider

With one hypervisor installed it is selected automatically; with several, the ambiguity is surfaced, never guessed.

Image catalog

artifact action=catalog lists maintained images: Talos (appliance and metal ISO), Ubuntu (cloud image and Vagrant), Debian, Fedora, Rocky, Alma, openSUSE, FreeBSD, Kali, TurnKey, the Windows dev VM, plus vagrant:org/box passthrough to the whole registry. Downloads are sha256-verified wherever the publisher provides a digest (GitHub release assets always do); unverified sources say so loudly. Vagrant boxes are fetched for the right provider and auto-extracted to their importable machine file. The cache lives in ~/.hypervisor-images (HV_IMAGE_DIR overrides).

Prerequisites

• VirtualBox (VBoxManage) and/or VMware Fusion / Workstation (vmrun). Detection is per-call, so a hypervisor installed mid-session is picked up.
• Nothing else: a single static Go binary, no Python, no Node.

Optional, detected at runtime: ovftool enables OVA import/export on VMware; xorriso enables repack_iso.

Installing

Published on the official MCP Registry as io.github.bryanjbelanger/desktop-hypervisor-mcp — that name is what registry-aware clients install by. The registry has no per-server page yet, so the listing itself is the API record: current entry.

For hosts that support MCP Bundles, download the .mcpb from the latest release and open it — guest credentials and the image cache directory are prompted for in the host's own UI. One bundle covers every platform; it carries a binary per (os, arch) and picks one at startup, so it is ~16 MB.

Otherwise take the bare binary for your platform from the same release, or build it:

go build -o desktop-hypervisor-mcp .

Registration with Claude Code

claude mcp add --scope user hypervisor -- /path/to/desktop-hypervisor-mcp

Guest-operation credentials come from the server environment, never from tool parameters:

claude mcp add --scope user hypervisor \
  --env HV_GUEST_USER=vagrant --env HV_GUEST_PASSWORD=vagrant \
  -- /path/to/desktop-hypervisor-mcp

(VMRUN_GUEST_USER/VMRUN_GUEST_PASSWORD are honored for compatibility.)

The server ships usage recipes in the MCP initialize handshake, generated from what was actually detected on the host — a session on a VirtualBox-only machine never pays context for VMware guidance.

Permissions

Per-tool allowlisting in .claude/settings.json keeps prompts meaningful — read-only tools are safe to always-allow:

{
  "permissions": {
    "allow": [
      "mcp__hypervisor__provider",
      "mcp__hypervisor__vm_info",
      "mcp__hypervisor__artifact",
      "mcp__hypervisor__snapshot"
    ]
  }
}

Keep mutating tools (vm_lifecycle, execute_command) behind prompts unless you accept unattended VM mutation.

Bundled skills

skills/ contains workflow skills for Claude Code — procedures that compose this server's tools across either hypervisor: hv-vm (provisioning), hv-network (networks, guest reachability, seed ISOs), hv-snapshot (safety workflows), hv-maintenance (inventory & cleanup), hv-transfer (clone/export/move). Install by copying (or symlinking) into ~/.claude/skills/. They supersede the predecessor's vbox-* skills.

Related projects

• talos-mcp-server — Talos/Kubernetes orchestration; consumes this server for node provisioning and stays deliberately hypervisor-agnostic.