virtualbox MCP server
Commit Oct 29, 2026Enables AI assistants to create, install, and operate virtual machines using vision-based GUI interaction or text-based guest execution.
Also known as chryaner/mcp-virtualbox
- Stars
- 7
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 29, 2026
- License
- MIT
What is virtualbox MCP?
virtualbox enables AI assistants to create, install, and operate virtual machines using vision-based GUI interaction or text-based guest execution.
Summary generated from the project's README
About virtualbox MCP server
Operating virtual machines through visual interaction or direct command execution is what this server enables for developers using AI assistants. It provides a bridge to VirtualBox 7.x, allowing an AI to manage the entire lifecycle of a guest operating system. Users can set up a machine by providing an ISO file and letting the assistant navigate installers using a vision loop that captures screenshots and simulates keyboard or mouse inputs.
This tool is designed for local use on Windows, Linux, or macOS hosts with Node.js 18+ installed. It offers 30 specific tools organized into categories like lifecycle management, display, input, guest control, network, and knowledge. While the vision loop works with any GUI, the server also supports text-based control via SSH, WinRM, or Guest Additions for faster command execution. This makes it possible to automate everything from bare metal OS installation to daily administrative tasks without human intervention.
What you can do with it
- 1Automated OS installationAsk the AI to install an operating system from an ISO file by watching the screen and typing commands.
- 2Remote command executionInstruct the AI to run specific commands inside a running guest machine using SSH or WinRM.
- 3Visual debugging of guest systemsRequest a screenshot of the virtual machine to see exactly what is happening on the guest display.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablechryaner/mcp-virtualbox is public and reachablegithub.com/chryaner/mcp-virtualbox ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-29github.com/chryaner/mcp-virtualbox ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubmcp-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? On a Windows host it is one command in Claude Code:
claude mcp add -s user terrarium -- npx -y terrarium-mcp mcp. Everything else is at 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
virtualbox MCP questions
What modes of operation does the server support?
It supports a Vision loop for GUI interaction (screenshot, read screen, keyboard/mouse) and a Text mode using SSH, WinRM, or Guest Additions.
What are the system requirements for mcp-virtualbox?
You need VirtualBox 7.x and Node.js version 18 or higher installed.
Can I use my own operating system installers?
Yes, you can provide your own OS installer ISO and instruct the AI on its location.