About Mcp Virtualbox
An MCP server that gives AI assistants tools to create, install, and operate VirtualBox virtual machines. It combines screenshot-and-input control for GUI tasks with SSH, WinRM, or Guest Additions for command execution.
Key features
- 01Create and manage virtual machines
- 02Capture screenshots and inspect screens
- 03Send keyboard and mouse input
- 04Run commands through SSH, WinRM, or Guest Additions
- 05Transfer files to and from guests
- 06Attach media and create snapshots
Use cases
- 01Install an operating system from an ISO
- 02Operate a guest through its graphical interface
- 03Run commands inside a guest machine
- 04Manage VM lifecycle and snapshots
MCP support
Exposes 30 VirtualBox management and guest-control tools to MCP clients, covering lifecycle, display, input, networking, and guest operations.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
Tools
30Saved tool list · updated 3w ago
This tool takes no parameters.
Details
From the project READMEmcp-virtualbox
Let AI see, click, type, and fully operate virtual machines - from bare metal OS installation to daily use, no human needed.
Heads up: the successor to this project is terrarium.
This repo started the "let an AI operate real VMs" idea. The next version grew different enough - immutable golden images, sub-second forks, revert-to-clean in seconds, and a full CLI alongside the MCP server - that it became its own project rather than a new release here.
Want the more advanced take? Head to terrarium. mcp-virtualbox stays maintained and available for anyone who wants the simpler, cross-platform VirtualBox MCP server it already is.
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:
- Vision loop - screenshot, read screen, send keyboard/mouse. Works with any OS, any installer, any GUI.
- 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
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.