mcp-virtualbox

Let AI see, click, type, and fully operate virtual machines - from bare metal OS installation to daily use, no human needed.

TL;DR

Claude Code (easy install)

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

Claude Code / Claude Desktop (manual)

Add to .mcp.json or claude_desktop_config.json:

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

Requires VirtualBox 7.x and Node.js 18+.

Provide your own OS installer ISO - just tell the AI where it is and what OS to install.

---

What is this

An MCP server that wraps VirtualBox, giving AI assistants 30 tools to create, install, and operate VMs through two modes:

1. Vision loop - screenshot, read screen, send keyboard/mouse. Works with any OS, any installer, any GUI.
2. Text mode - SSH, WinRM, or Guest Additions for fast command execution.

How it works

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

Tools

30 tools across 6 categories:

Category	Tools
Lifecycle (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
Display (2)	vm_screenshot vm_screen_info
Input (3)	vm_keyboard_scancode vm_keyboard_type vm_mouse_click
Guest Control (3)	vm_guest_exec vm_guest_copy_to vm_guest_copy_from
Network (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
Knowledge (1)	vm_install_guide

Testing status

	Windows XP	Windows 7/10/11	Ubuntu/Linux
OS install (vision loop)	x	-	-
Guest Additions	x	-	-
Guest exec	x	-	-
SSH	-	-	-
WinRM	-	-	-
Screenshot + keyboard	x	-	-
Mouse click	x	-	-

Host platforms: Windows x64 (tested), Linux/macOS (should work).

x = tested, - = should work, not yet verified

Environment variables

Variable	Default
VBOXMANAGE_PATH	Auto-detected
VBOXMANAGE_DRY_RUN	false
VBOXMANAGE_DEBUG	false

From source

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

Python 3 with vboxapi module is optional (only needed for vm_mouse_click).

License

MIT