mcp-virtualbox

mcp-virtualbox

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

A single static Go binary MCP server that wraps VBoxManage and gives AI assistants 41 tools to create, install, and operate VMs. This started as a Go port of chryaner/mcp-virtualbox (originally TypeScript) and adds more input, networking, lifecycle, and safety tooling — no Node.js and no Python runtime required.

Why a Go port

• One binary, zero runtime deps. go build produces a single executable. No npx, no node_modules, no Python vboxapi for the mouse.
• Pure-Go absolute mouse. Mouse clicks go through the VirtualBox web service over SOAP instead of shelling out to a Python helper.
• Maintained WinRM. Windows command execution uses the masterzen/winrm library (NTLM-capable) instead of hand-rolled SOAP + regex XML parsing.
• Cross-compiles trivially for Linux, Windows, and macOS.

Two modes of control

1. Vision loop — vm_screenshot → analyze → vm_keyboard_* / vm_mouse_click → repeat. Works with any OS, any installer, any GUI.
2. Text mode — Guest Additions (vm_guest_exec), SSH (vm_exec_ssh), or WinRM (vm_exec_winrm) for fast command execution once the OS is up.

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

Requirements

Core (always needed)

• VirtualBox 7.x — the VBoxManage CLI must be on PATH (or in a standard install location; it's auto-detected). The VirtualBox SDK / Python vboxapi is NOT required — mouse control uses the bundled vboxwebsrv web service, not Python.
• Linux: your user must be in the vboxusers group.

Per-feature

• Mouse (vm_mouse_click / vm_mouse_move / vm_mouse_scroll / vm_mouse_drag): the VirtualBox web service vboxwebsrv (ships with VirtualBox). Auto-started on demand — see Mouse setup.
• Clipboard paste (vm_paste_text): a host clipboard helper and Guest Additions with clipboard sharing running in the guest. On Linux install xclip or xsel — VirtualBox reads the X11 clipboard, so on a Wayland session (e.g. KDE Plasma) XWayland must be available and a Wayland-only wl-copy will not sync to the guest. macOS uses pbcopy, Windows uses PowerShell.
• Guest control (vm_guest_exec, vm_guest_copy_to / vm_guest_copy_from): Guest Additions installed and running in the guest.
• SSH / WinRM (vm_exec_ssh / vm_exec_winrm): an SSH or WinRM server enabled in the guest.

Building from source

• Go 1.25+ — only if you go install or build locally. The plugin ships prebuilt binaries, so plugin users need no Go.

Windows plugin install

• curl.exe and tar.exe — bundled with Windows 10+ (the launcher uses them to fetch the prebuilt binary).

Install

First install the binary (both methods below need it on your PATH; go install puts it in ~/go/bin):

go install github.com/mb85/mcp-virtualbox@latest

Or build from source:

git clone https://github.com/mb85/mcp-virtualbox
cd mcp-virtualbox
make build        # -> ./mcp-virtualbox

Claude Code plugin (easiest — no Go required)

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

Works on Linux, macOS, and Windows with no Go toolchain. The plugin uses a mcp-virtualbox binary from your PATH if present; otherwise a launcher downloads the matching prebuilt release binary on first run and caches it (scripts/mcp-virtualbox-launch on Unix, scripts/mcp-virtualbox-launch.cmd on Windows — both selected automatically from the one command). Windows needs curl.exe/tar.exe (bundled with Windows 10+). To force an update, delete bin/mcp-virtualbox in the plugin directory.

Manual MCP configuration

Add to .mcp.json (Claude Code) or claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-virtualbox": {
      "command": "/path/to/mcp-virtualbox"
    }
  }
}

Or via CLI: claude mcp add mcp-virtualbox -s user -- ~/go/bin/mcp-virtualbox.

Optional environment overrides are listed by mcp-virtualbox --help.

Tools

41 tools across 8 categories:

Reliable text entry

vm_keyboard_type simulates keystrokes and can drop characters on long or Unicode text (the guest keyboard buffer overruns). For that, prefer vm_paste_text, which sets the host clipboard, lets VirtualBox's shared clipboard sync it to the guest, then sends a paste chord (ctrl+v by default; use shift+insert for Linux terminals). It requires Guest Additions with clipboard sharing in the guest, a running VM with the target field focused, and a clipboard helper on the host. On Linux install xclip or xsel (VirtualBox reads the X11 clipboard; on Wayland it works through XWayland — wl-copy alone does not sync); macOS uses pbcopy, Windows uses PowerShell.

Read-only / safety mode

Set VBOX_READONLY=true to disable every mutating tool (create, delete, modify, start/stop, snapshot, input injection, guest/host command execution, …). Only observation tools remain: vm_list, vm_info, vm_screen_info, vm_screenshot, vm_list_ostypes, vm_install_guide, vm_get_guest_ip, vm_list_host_networks, and the waiters. Useful when pointing an agent at production VMs.

Mouse setup

VBoxManage has no CLI command for mouse events, so vm_mouse_click drives the guest pointer through the VirtualBox web service (vboxwebsrv).

This happens automatically. The first time a mouse click is needed, the server starts vboxwebsrv on demand (setting anonymous auth via websrvauthlibrary null when no credentials are configured) and retries. No manual setup is required in the default configuration.

If you'd rather manage the service yourself, set VBOXWEB_AUTOSTART=false and start it manually (or with the included scripts/setup-vboxweb.sh):

VBoxManage setproperty websrvauthlibrary null
vboxwebsrv --host 127.0.0.1 --port 18083 &

Related environment variables: VBOXWEB_ENDPOINT, VBOXWEB_USER, VBOXWEB_PASSWORD, VBOXWEB_AUTOSTART, VBOXWEB_BIN. All other tools work without the web service.

Absolute positioning also requires USB tablet mouse mode, which vm_create enables automatically (--mouse usbtablet).

Development

make build   # build the binary
make test    # go test ./...
make check   # gofmt check + go vet + tests

See CLAUDE.md for architecture notes.

Credits

Port of chryaner/mcp-virtualbox by Eiliya Raizis. MIT licensed; see LICENSE.