VirtualBox MCP
# VirtualBox MCP
A [Model Context Protocol](https://modelcontextprotocol.io) server that lets AI applications and agents manage Oracle VirtualBox virtual machines. It can also run commands inside Linux and Windows guests through Bash, POSIX sh, PowerShell and CMD.
> **Status: early development (0.1.0, unreleased).** The core modules are written, but the MCP tool layer, transports and tests are still being built. See [CHANGELOG.md](CHANGELOG.md).
## Features
| Area | Status |
|---|---|
| VirtualBox detection (Windows, Linux, macOS) | Implemented |
| VM discovery, lifecycle, creation, clone, import/export | Manager implemented |
| Guest execution: Guest Control, SSH, WinRM | Backends implemented |
| Bash, POSIX sh, PowerShell (5.1 / 7), CMD | Implemented |
| Persistent interactive terminals | Manager implemented |
| File management and transfers | Manager implemented |
| Permission engine, approvals, redaction, audit log | Implemented |
| Packages, administration, snapshots, networking, storage, devices, monitoring, orchestration | Planned |
| MCP tools (core VM, execution and file tools) | Implemented |
| MCP resources, prompts, remaining tools | Planned |
| STDIO transport and CLI (`serve`, `health`, `stop`, `resume`) | Implemented |
| Authenticated Streamable HTTP transport | Planned |
## Requirements
- Node.js 20 or newer
- VirtualBox 6.0 or newer (7.x recommended)
- For guest execution: Guest Additions, an SSH server (Linux), or WinRM (Windows)
## Quick start (development)
```bash
npm install
```
```bash
npm run build
```
Configuration is described in [docs/CONFIGURATION.md](docs/CONFIGURATION.md).
## Documentation
- [Architecture](docs/ARCHITECTURE.md)
- [Installation](docs/INSTALLATION.md)
- [Configuration](docs/CONFIGURATION.md)
- [Tools reference](docs/TOOLS-REFERENCE.md)
- [Security model](docs/SECURITY-MODEL.md)
- [Guest setup](docs/GUEST-SETUP.md)
- [Troubleshooting](docs/TROUBLESHOOTING.md)
- [Examples](docs/EXAMPLES.md)
- [Development and Git Flow](docs/DEVELOPMENT.md)
## Community
- [Contributing](CONTRIBUTING.md)
- [Code of conduct](CODE_OF_CONDUCT.md)
- [Security policy](SECURITY.md)
- [Support](SUPPORT.md)
## License
MIT. See [LICENSE.md](LICENSE.md).
TDQS
Scored across 27 tools
Most tools target a distinct action+resource, and the async command trio (execute_command_async, get_command_status, get_command_output, wait_for_command) is carefully differentiated in the descriptions. The only real overlap is list_vms vs list_running_vms (the latter is just a filtered view) and get_vm_state vs get_vm_info (state is a subset of info), plus several closely-related power tools whose distinctions are at least spelled out.
All 27 tools use consistent snake_case verb_noun form (list_vms, get_vm_info, start_vm, poweroff_vm, write_guest_file, cancel_command). Even the async variant (execute_command_async) and paging helpers follow the same predictable pattern.
At 27 tools the surface is heavy for a VM manager, split across four sub-domains (VM lifecycle, command execution, guest files, host/info). Each tool is individually justified and not obviously padded, but a few (list_running_vms, get_vm_state) could be folded into broader tools to slim the set.
Power/lifecycle control of existing VMs, guest command execution, and guest file CRUD are well covered, but there is no create/register/clone VM, no unregister/delete VM, no snapshot operations (take/restore/list), and no way to modify VM configuration (CPU, memory, network). An agent asked to provision or snapshot a VM will hit a dead end.