desktop-hypervisor-mcp

桌面虚拟机管理程序 MCP

一款与提供商无关的 MCP 服务，适用于桌面虚拟机管理程序：VirtualBox、 VMware Fusion 和 VMware Workstation。提供 9 个工具，约占 1,800 个上下文 令牌，即可完整覆盖此前两个服务约 5,600 个令牌所提供的功能。

它接替了 virtualbox-mcp-server（相关历史保留在 predecessor-virtualbox 分支），并将从未发布的 vmware-fusion-mcp-server 的功能 整合到同一基于能力的接口中。

版本说明： 此服务的稳定版本从 v2.0.0 开始。v1.x 系列（以及为仍在固定使用该版本的用户保留的 v1.0.0 版本）属于仅支持 VirtualBox 的前身；0.x 标签则是此服务稳定发布前的迭代版本。v2.0.0 的内容与 v0.4.3 完全相同，只是重新编号为稳定版本系列。

设计

• 基于能力，而非最低公分母。 提供商会公布自己实际支持的功能（provider action=list）：来宾执行、OVA 导入/导出、链接克隆、启动前 guestinfo 注入、通过 DHCP 租约发现 IP、制作 ISO……不支持的操作会指出缺少的能力，而不会只返回提供商错误。
• 表达意图，而非机制。 “确保集群节点共享主机可访问的网络”在两类平台上都能实现；“创建仅主机接口”则不行。通用工具表达意图；提供商原生机制仍可通过 execute_command 直接使用，不做抽象。
• 按提供商解析构件。 同一映像名称会为各虚拟机管理程序匹配其实际可导入的构件——Talos 的 vmware-*.ova 与 virtualbox-*.ova、Vagrant 的 vmware_desktop 与 virtualbox box、Microsoft 针对不同虚拟机管理程序提供的开发虚拟机——以（映像、提供商系列、主机架构）为键进行匹配。

工具

工具	操作
provider	list — 列出已安装的虚拟机管理程序及其状态、能力、格式，以及未就绪时的解决方法
artifact	catalog、resolve、fetch（dry_run）— 按提供商下载经过验证的官方 OS 映像
vm_lifecycle	create、start、stop、suspend、reset、delete、clone、import、export
vm_info	list、running、show、ip（使用来宾工具；否则按 MAC 地址查询 DHCP 租约——适用于 Talos 等无需 Agent 的来宾）
vm_config	resources、nested_virt、attach_iso、guestinfo（启动前键值注入，VMware）
snapshot	take、restore、delete、list（树状结构）
guest	exec、script、copy_in、copy_out、screenshot
network	ensure_cluster_network、expose_guest_port、make_iso、repack_iso
execute_command	在所选提供商上执行原始 VBoxManage / vmrun argv

只安装一个虚拟机管理程序时会自动选用；安装多个时会提示存在歧义，绝不擅自猜测。

映像目录

artifact action=catalog 会列出维护中的映像：Talos（设备映像和裸机 ISO）、Ubuntu（云映像和 Vagrant）、Debian、Fedora、Rocky、Alma、openSUSE、FreeBSD、Kali、TurnKey、Windows 开发虚拟机，以及可传递至整个注册表的 vagrant:org/box。只要发布方提供摘要，下载都会通过 sha256 校验（GitHub 发布资源始终提供摘要）；未校验的来源会明确标示。Vagrant box 会按正确的提供商下载，并自动解压为可导入的机器文件。缓存位于 ~/.hypervisor-images（可通过 HV_IMAGE_DIR 覆盖）。

先决条件

• VirtualBox（VBoxManage）和/或 VMware Fusion / Workstation（vmrun）。 每次调用时都会检测，因此会话中途安装的虚拟机管理程序也能被发现。
• 无其他依赖：单个静态 Go 二进制文件，无需 Python 或 Node。

可选组件，运行时检测：ovftool 可在 VMware 上启用 OVA 导入/导出； xorriso 可启用 repack_iso。

安装

已发布到官方 MCP Registry，名称为 io.github.bryanjbelanger/desktop-hypervisor-mcp——注册表感知型客户端会按此名称安装。注册表目前还没有单个服务的页面，因此列表条目本身就是 API 记录： 当前条目。

对于支持 MCP Bundles 的宿主，下载最新版本中的 .mcpb 并打开——宿主自己的界面会提示输入虚拟机凭据和镜像缓存目录。一个 bundle 适用于所有平台；它包含各个（os、arch）组合对应的二进制文件，并在启动时选择其中一个，因此大小约为 16 MB。

否则，请从同一版本中获取适用于你平台的独立二进制文件，或自行构建：

go build -o desktop-hypervisor-mcp .

在 Claude Code 中注册

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

虚拟机操作凭据来自服务环境，而不是工具参数：

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。）

服务会在 MCP 初始化握手中提供用法指南，这些指南根据宿主上实际检测到的内容生成——仅运行 VirtualBox 的机器上的会话不会为 VMware 指南消耗上下文。

权限

在 .claude/settings.json 中按工具设置允许列表，可以让提示保持有意义——只读工具可以始终允许：

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

除非你接受在无人值守时修改虚拟机，否则请将会修改数据的工具（vm_lifecycle、execute_command）设为需要提示确认。

内置技能

skills/ 包含适用于 Claude Code 的工作流技能——可组合使用此服务工具、适用于任一虚拟机监控程序的操作流程： hv-vm（配置）， hv-network（网络、客户机可达性、种子 ISO）， hv-snapshot（安全工作流）， hv-maintenance（清点与清理）， hv-transfer（克隆/导出/迁移）。 复制（或创建符号链接）到 ~/.claude/skills/ 即可安装。这些技能取代了前代的 vbox-* 技能。

相关项目

• talos-mcp-server — Talos/Kubernetes 编排；使用此服务配置节点，并有意保持与虚拟机监控程序无关。