Mcp Virtualbox

mcp-virtualbox

让 AI 查看、点击、输入并全面操作虚拟机——从裸机操作系统安装到日常使用，全程无需人工介入。

注意：此项目的后继项目是 terrarium。

此仓库开启了“让 AI 操作真实虚拟机”这一构想。下一个版本发展出了足够多的不同之处——不可变的黄金镜像、亚秒级分叉、数秒内恢复到干净状态，以及与 MCP 服务并行提供的完整 CLI——因此它成为了一个独立项目，而不是此处的新版本。

想体验更高级的方案？请访问 terrarium。 mcp-virtualbox 会继续维护并保持可用，供希望使用现有这款更简单、跨平台 VirtualBox MCP 服务的用户选择。

简介

Claude Code（轻松安装）

/plugin marketplace add chryaner/mcp-virtualbox
/plugin install mcp-virtualbox@mcp-virtualbox

Claude Code / Claude Desktop（手动安装）

添加到 .mcp.json 或 claude_desktop_config.json：

{
  "mcpServers": {
    "mcp-virtualbox": {
      "command": "npx",
      "args": ["-y", "mcp-virtualbox"]
    }
  }
}

需要 VirtualBox 7.x 和 Node.js 18+。

请自行准备操作系统安装程序 ISO——只需告诉 AI ISO 文件的位置以及要安装的操作系统。

---

这是什么

一个封装 VirtualBox 的 MCP 服务，为 AI 助手提供 30 个工具，通过两种模式创建、安装和操作虚拟机：

1. 视觉循环 - 截屏、读取屏幕、发送键盘和鼠标输入。适用于任何操作系统、任何安装程序和任何图形界面。
2. 文本模式 - 通过 SSH、WinRM 或 Guest Additions 快速执行命令。

工作原理

vm_create("WindowsXP")          -> VM with correct settings (IDE, 512MB RAM)
vm_attach_media(iso)             -> Mount installer ISO
vm_install_guide("xp")           -> Step-by-step guide with gotchas
vm_screenshot()                  -> AI sees "Welcome to Setup"
vm_keyboard_scancode("enter")    -> AI presses Enter
  ... repeat until installed ...
vm_guest_exec("cmd.exe", ["/c", "dir"])  -> Text-based control

工具

6 个类别共 30 个工具：

类别	工具
生命周期（15）	vm_list vm_info vm_create vm_start vm_stop vm_delete vm_pause vm_resume vm_reset vm_attach_media vm_snapshot vm_modify vm_list_ostypes vm_shared_folder_add vm_shared_folder_remove
显示（2）	vm_screenshot vm_screen_info
输入（3）	vm_keyboard_scancode vm_keyboard_type vm_mouse_click
客户机控制（3）	vm_guest_exec vm_guest_copy_to vm_guest_copy_from
网络（6）	vm_exec_ssh vm_exec_winrm vm_get_guest_ip vm_wait_for_guest_additions vm_wait_for_network vm_add_nat_port_forward
知识（1）	vm_install_guide

测试状态

	Windows XP	Windows 7/10/11	Ubuntu/Linux
操作系统安装（视觉循环）	x	-	-
Guest Additions	x	-	-
客户机命令执行	x	-	-
SSH	-	-	-
WinRM	-	-	-
截屏 + 键盘	x	-	-
鼠标点击	x	-	-

主机平台： Windows x64（已测试）、Linux/macOS（应可正常运行）。

x = 已测试，- = 应可正常运行，但尚未验证

环境变量

变量	默认值
VBOXMANAGE_PATH	自动检测
VBOXMANAGE_DRY_RUN	false
VBOXMANAGE_DEBUG	false

从源代码安装

git clone https://github.com/chryaner/mcp-virtualbox.git
cd mcp-virtualbox
npm install && npm run build

Python 3 和 vboxapi 模块为可选项（仅 vm_mouse_click 需要）。

许可证

MIT