README.md
A powerful Model Context Protocol (MCP) server for managing VirtualBox VMs.
🖥️ VirtualBox MCP Server
A powerful Model Context Protocol (MCP) server for managing VirtualBox VMs via Vagrant.
AI agents can now provision, manage, and debug virtual development environments with full observability.
Features • Quick Start • Tools • Workflows • Examples • Configuration
✨ Features
- 38 MCP Tools for complete VM lifecycle management
- Real-time Observability with logs, dashboards, and progress tracking
- Snapshot Management for safe rollback and recovery
- Process Control with kill/list capabilities
- File Synchronization with conflict resolution
- Async Operations with progress tracking and cancellation
- System Guardrails for zombie VM detection and cleanup
- Sequential Thinking for AI problem-solving
📦 Architecture
Virtualbox-mcp-server/ # Turborepo Monorepo
├── apps/
│ └── mcp-server/ # Main MCP server (38 tools)
│ └── src/
│ ├── index.ts # Tool definitions & handlers
│ ├── error-handler.ts
│ ├── port-manager.ts
│ └── sequential-thinking.ts
├── packages/
│ ├── vagrant-client/ # Vagrant CLI wrapper
│ ├── sync-engine/ # Chokidar + file sync
│ └── shared-utils/ # Logger utilities
├── turbo.json
└── package.json
🚀 Quick Start
Prerequisites
- Node.js 18+
- VirtualBox 6.x or 7.x
- Vagrant 2.3+
Installation
# Install via NPM (Recommended)
npm install -g @use.manus.ai/virtualbox-mcp-server
# Or Clone and Build from Source
git clone https://github.com/usemanusai/Virtualbox-mcp-server.git
cd Virtualbox-mcp-server
# Install dependencies
npm install
# Build all packages
npm run build
Running the Server
# Run the installed server
virtualbox-mcp-server
# Or run from source
node apps/mcp-server/dist/index.js
🛠️ All 38 Tools
VM Lifecycle (6 tools)
| Tool | Description |
|---|---|
create_vm |
Create a new Vagrant VM |
create_dev_vm |
Create VM with full config (CPU, memory, ports, sync) |
ensure_dev_vm |
Start or create VM if not exists |
get_vm_status |
Get VM state |
list_vms |
List all VMs |
destroy_vm |
Destroy VM (force) |
Execution (3 tools)
| Tool | Description |
|---|---|
exec_command |
Execute command in VM (with timeout) |
exec_with_sync |
Execute with rsync before/after |
run_background_task |
Run nohup background task |
Environment Setup (3 tools)
| Tool | Description |
|---|---|
setup_dev_environment |
Install runtimes (node, python, go, etc.) |
install_dev_tools |
Install tools (git, docker, nginx, etc.) |
configure_shell |
Configure aliases and env vars |
File Operations (7 tools)
| Tool | Description |
|---|---|
upload_file |
Upload file to VM |
search_files |
Grep search in VM |
configure_sync |
Configure file watcher |
sync_to_vm |
Rsync host→VM |
sync_from_vm |
Rsync VM→host |
sync_status |
Get sync state |
resolve_conflict |
Resolve sync conflicts |
👁️ Observability (3 tools)
| Tool | Description |
|---|---|
tail_vm_log |
Read last N lines of a log file (e.g., /var/log/syslog) |
get_task_output |
Get stdout/stderr of background tasks |
grep_log_stream |
Search for patterns in log files |
📸 Snapshots (4 tools)
| Tool | Description |
|---|---|
snapshot_save |
Create named snapshot before risky operations |
snapshot_restore |
Revert to a specific snapshot |
snapshot_list |
List all available snapshots |
snapshot_delete |
Delete a specific snapshot |
⚙️ Process Control (2 tools)
| Tool | Description |
|---|---|
list_processes |
Return structured list of running processes (ps aux) |
kill_process |
Send SIGTERM/SIGKILL to a process |
🌐 Network (1 tool)
| Tool | Description |
|---|---|
check_vm_port |
Verify if port is listening in VM & accessible from host |
📊 Dashboard (1 tool)
| Tool | Description |
|---|---|
| `g |
Tools (18)
create_vmCreate a new Vagrant VMcreate_dev_vmCreate VM with full config (CPU, memory, ports, sync)ensure_dev_vmStart or create VM if not existsget_vm_statusGet VM statelist_vmsList all VMsdestroy_vmDestroy VM (force)exec_commandExecute command in VM (with timeout)exec_with_syncExecute with rsync before/afterrun_background_taskRun nohup background tasksetup_dev_environmentInstall runtimes (node, python, go, etc.)install_dev_toolsInstall tools (git, docker, nginx, etc.)configure_shellConfigure aliases and env varsupload_fileUpload file to VMsearch_filesGrep search in VMsnapshot_saveCreate named snapshot before risky operationssnapshot_restoreRevert to a specific snapshotlist_processesReturn structured list of running processes (ps aux)check_vm_portVerify if port is listening in VM & accessible from hostConfiguration
claude_desktop_config.json
{
"mcpServers": {
"virtualbox": {
"command": "virtualbox-mcp-server",
"env": {}
}
}
}Try it
→Create a new development VM with 2 CPUs and 4GB of RAM.
→Install Docker and Nginx on my current virtual machine.
→Take a snapshot of the VM named 'pre-deployment-test' before I run this script.
→Check if port 8080 is listening inside the VM and accessible from my host.
→List all running processes in the VM and kill the one using the most memory.