Skip to main content
Glama

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 (serve, health, stop, resume)

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 install
npm run build

Configuration is described in docs/CONFIGURATION.md.

Documentation

Community

License

MIT. See LICENSE.md.

Available Tools

27 tools
cancel_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

    C2.8/5.0

    Scored across 27 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count3/5

    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.

    Completeness2/5

    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

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to interact with Ubuntu VMs via SSH, including executing commands, simulating keyboard/mouse input, capturing screenshots, and controlling GUI applications remotely.
      1
      -
    • A
      license
      B
      quality
      B
      maintenance
      Enables 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.
      9
      19
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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