You run a dedicated MCP server that lets you manage VirtualBox VMs via Vagrant using code-driven tools. This server provides observability, lifecycle automation, file sync, snapshots, and safe rollback—so you can provision, monitor, and debug development environments with confidence.

How to use

You interact with the MCP server through an MCP client that talks JSON-RPC to the local server. Use the client to list, create, start, stop, and inspect VMs, run commands inside VMs, synchronize files, manage snapshots, and observe dashboards and logs. The server exposes a broad set of tools that you can compose into practical workflows, such as booting a dev VM, synchronizing code, installing dev tools, checking service health, and rolling back after risky updates.

How to install

# Prerequisites
node.js 18+
VirtualBox 6.x or 7.x
Vagrant 2.3+

# Clone the server repository
git clone https://github.com/usemanusai/Virtualbox-mcp-server.git
cd Virtualbox-mcp-server

# Install dependencies
npm install

# Build all packages
npm run build

# Start the MCP server (direct)
node apps/mcp-server/dist/index.js

# Or start via the workspace shortcut (if you prefer monorepo tooling)
npm run start --workspace=virtualbox-mcp-server
```} ,{

Additional configuration and notes

The MCP server is designed to run locally and communicate with the VirtualBox and Vagrant tooling on your host. You can configure the server’s runtime behavior through environment variables and, when applicable, through MCP client configuration. The examples below show common environment keys you may encounter or adapt for your setup.

# Example environment setup for development on Windows/PowerShell
LOG_LEVEL=debug
PATH=C:\Program Files (x86)\Vagrant\bin;C:\Program Files\Oracle\VirtualBox;%PATH%

# Example environment setup for Linux/macOS
LOG_LEVEL=info
VAGRANT_HOME=/home/you/.vagrant.d
VM_DEFAULT_BOX=ubuntu/jammy64
VM_DEFAULT_MEMORY=4096
VM_DEFAULT_CPU=4

Start the server with an explicit config (if using a dedicated script)

node apps/mcp-server/dist/index.js

If you use a monorepo workflow for building and starting a single package

npm run start --workspace=virtualbox-mcp-server

Available tools

create_vm

Create a new Vagrant VM with a given name and box

create_dev_vm

Create a VM with full configuration including CPU, memory, ports, and sync folders

ensure_dev_vm

Start or create a VM if it does not exist

get_vm_status

Query the current status of a VM (running, stopped, etc.)

list_vms

List all VMs currently managed by the MCP server

destroy_vm

Destroy a VM (force)

exec_command

Execute a command inside a VM with an optional timeout

exec_with_sync

Execute a command inside a VM with pre/post file synchronization

run_background_task

Run a command inside a VM in the background

setup_dev_environment

Install runtimes and base tools inside the VM or host

install_dev_tools

Install tools such as git, docker, nginx, etc.

configure_shell

Configure shell aliases and environment variables for convenience

upload_file

Upload a file from host to VM

search_files

Search for files inside the VM

configure_sync

Configure file watcher or rsync-based sync between host and VM

sync_to_vm

Sync files from host to VM

sync_from_vm

Sync files from VM to host

sync_status

Get the current sync state between host and VM

resolve_conflict

Resolve file synchronization conflicts

tail_vm_log

Read the tail of a VM log file

get_vm_dashboard

Collect a comprehensive resource and task dashboard for a VM

start_download

Begin a tracked download operation with an operation ID

get_operation_progress

Query real-time progress of an ongoing operation

wait_for_operation

Block until an operation completes or times out

cancel_operation

Cancel an ongoing operation

list_active_operations

List currently active operations

scan_system_health

Check system health and identify zombie VMs

cleanup_zombies

Safely terminate orphaned VMs with optional dry-run

sequentialthinking

AI-assisted reasoning to formulate problem-solving steps

snapshot_save

Create a named VM snapshot for rollback

snapshot_restore

Restore VM to a named snapshot

snapshot_list

List available VM snapshots

snapshot_delete

Delete a VM snapshot

check_vm_port

Verify if a port is listening inside the VM

grep_log_stream

Search for patterns in VM log files

list_processes

Return a structured list of running processes in a VM

kill_process

Terminate a process inside the VM

check_vm_port

Verify port status inside a VM

get_vm_dashboard

Provide a full performance and status dashboard for a VM

start_download

Initiate a large file download to a VM

snapshot_save

Create a safe checkpoint before risky operations