VirtualBox MCP
Allows AI applications and agents to manage Oracle VirtualBox virtual machines, including VM discovery, lifecycle operations, creation, cloning, and import/export. It also supports running commands inside Linux and Windows guests via Guest Control, SSH, or WinRM, plus persistent terminals and file management.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@VirtualBox MCP start my Ubuntu VM and run uname -a inside it"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
VirtualBox MCP
A Model Context Protocol 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.
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 ( | Implemented |
Authenticated Streamable HTTP transport | Planned |
Related MCP server: virtualization-mcp
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)
npm installnpm run buildConfiguration is described in docs/CONFIGURATION.md.
Documentation
Community
License
MIT. See LICENSE.md.
Available Tools
27 toolscancel_commandC
Cancel a running command.
Inputs: id (required).
delete_guest_fileA
Delete a file or directory in the guest. Recursive deletes and protected system paths need approval.
Inputs: vm (required), path (required), directory, recursive, +1 more.
detect_guest_osC
Detect the guest OS family and Guest Additions status.
Inputs: vm (required).
discard_saved_stateC
Discard a VM's saved state.
Inputs: vm (required), approvalId.
execute_commandC
Run a command in the guest OS and wait for its result.
Inputs: vm (required), command (required), cwd, env, +4 more.
execute_command_asyncB
Start a command in the guest and return immediately with a command ID (poll with get_command_status).
Inputs: vm (required), command (required), cwd, env, +4 more.
get_command_historyC
Recent commands, optionally for one VM.
Inputs: vm, limit.
get_command_outputC
Page through a command's stdout or stderr.
Inputs: id (required), limit, offset, stream.
get_command_statusA
Status of a command started earlier (output sizes only; use get_command_output for content).
Inputs: id (required).
get_host_infoA
VirtualBox host information (CPU, memory, VirtualBox version).
Inputs: no named parameters.
get_vm_infoC
Detailed configuration and state of one VM.
Inputs: vm (required).
get_vm_stateC
Current power state of a VM.
Inputs: vm (required).
list_available_shellsC
Shells available in the guest.
Inputs: vm (required), refresh.
list_guest_filesC
List a directory in the guest.
Inputs: vm (required), path (required), showHidden.
list_running_vmsB
List running VMs.
Inputs: no named parameters.
list_vmsC
List VirtualBox VMs visible under the current policy, optionally filtered.
Inputs: tag, group, query, state.
pause_vmB
Pause a running VM.
Inputs: vm (required).
poweroff_vmA
Force power-off (like pulling the plug). Unsaved guest data is lost.
Inputs: vm (required), approvalId.
read_guest_fileC
Read a file from the guest.
Inputs: vm (required), path (required), encoding, maxBytes.
reset_vmA
Hard reset a VM. Unsaved guest data is lost.
Inputs: vm (required), approvalId.
resume_vmC
Resume a paused VM.
Inputs: vm (required).
save_vm_stateB
Save the VM state to disk and stop it.
Inputs: vm (required).
shutdown_vmA
Gracefully shut down a VM (ACPI power button). Never forces power-off.
Inputs: vm (required), waitMs.
start_vmD
Start a VM.
Inputs: vm (required), type.
wait_for_commandC
Wait for an async command to finish and return its result.
Inputs: id (required), timeoutMs.
wait_for_vm_stateC
Wait until a VM reaches one of the given states.
Inputs: vm (required), states (required), timeoutMs.
write_guest_fileA
Write (or append to) a file in the guest. Protected system paths need approval.
Inputs: vm (required), path (required), content (required), append, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
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.
Maintenance
Related MCP Connectors
Linux VMs for AI agents: create VMs, run commands, edit files and open preview URLs.
Manage Vozora VPS servers, SSH keys, firewalls, DNS and usage from an AI agent.
Cloud Linux VMs for your agent: run code, Docker, files and HTTPS previews in a Sandboxer microVM.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with Ubuntu VMs via SSH, including executing commands, simulating keyboard/mouse input, capturing screenshots, and controlling GUI applications remotely.1-
- AlicenseBqualityBmaintenanceEnables AI assistants to manage virtual machines, sandboxes, and dev environments through VirtualBox, Hyper-V, and Windows Sandbox, supporting VM lifecycle, ISO downloads, networking, and unattended installs.919MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage virtual machines via natural language, including creating, editing, and VNC control.9 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables LLMs to remotely control VirtualBox VMs and Playwright browsers on Windows, including VM lifecycle actions, in-guest commands, browser automation, window management, and service monitoring via REST API and MCP.MIT