Which integrations are available for this server?

Provides tools to create and manage virtual development environments using the Vagrant CLI, including VM creation and status retrieval. Enables programmatic management and monitoring of VirtualBox virtual machines through the Model Context Protocol.

How do I use Virtualbox MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Virtualbox MCP Server create a new VM named 'dev-server' using ubuntu/focal64" 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 Server

TypeScript MCP SDK License: MIT Turborepo

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

flowchart TB subgraph AI["🤖 AI Agent"] Claude["Claude / GPT / Gemini"] end subgraph MCP["📡 MCP Server"] McpServer["virtualbox-mcp-server"] Tools["38 Tools"] Thinking["Sequential Thinking"] end subgraph Packages["📦 Internal Packages"] VC["vagrant-client"] SE["sync-engine"] SU["shared-utils"] end subgraph VM["💻 VirtualBox / Vagrant"] VM1["dev-vm"] VM2["test-vm"] VM3["prod-replica"] end Claude -->|"MCP JSON-RPC"| McpServer McpServer --> Tools McpServer --> Thinking Tools --> VC Tools --> SE VC --> SU SE --> SU VC -->|"vagrant up/ssh"| VM1 VC -->|"vagrant ssh"| VM2 VC -->|"vagrant status"| VM3

🚀 Quick Start

Prerequisites

Node.js 18+
VirtualBox 6.x or 7.x
Vagrant 2.3+

Installation

# Clone the 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

Running the Server

# Start the MCP server npm run start --workspace=virtualbox-mcp-server # Or directly 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
`get_vm_dashboard`	Comprehensive dashboard: CPU, RAM, Disk, tasks, logs

⏳ Progress Awareness (5 tools)

Tool	Description
`start_download`	Start tracked download, returns operation_id
`get_operation_progress`	Get real-time progress (bytes, %, ETA)
`wait_for_operation`	Block until operation completes or times out
`cancel_operation`	Cancel a running operation
`list_active_operations`	List all active operations

🛡️ Guardrails & Maintenance (2 tools)

Tool	Description
`scan_system_health`	Check disk/memory, identify Zombie VMs
`cleanup_zombies`	Safely destroy orphaned VMs (with dry-run option)

🧠 AI Reasoning (1 tool)

Tool	Description
`sequentialthinking`	Dynamic problem-solving with reflection & branching

🔄 Architectural Workflows

🟢 Easy Workflows

1. The "Daily Standup" (Environment Prep)

Quickly bring a dev environment online and ensure it's ready:

flowchart LR A["ensure_dev_vm"] --> B["sync_to_vm"] B --> C["install_dev_tools"] C --> D["get_vm_dashboard"]

ensure_dev_vm — Boot or create the VM automatically
sync_to_vm — Push local code changes to VM
install_dev_tools — Verify tools are present
get_vm_dashboard — Confirm VM is healthy

2. The "Dataset Fetch" (Async Download)

Download large files without blocking:

flowchart LR A["start_download"] --> B["wait_for_operation"] B --> C["search_files"]

start_download — Initiate download, get operation_id
wait_for_operation — Block until download completes
search_files — Verify file exists at expected path

3. The "Service Pulse" (Basic Debugging)

Quickly diagnose why localhost:8080 isn't loading:

flowchart LR A["list_vms"] --> B["check_vm_port"] B --> C["tail_vm_log"]

list_vms — Identify which VM handles the service
check_vm_port — Check if app is listening (vs. port forwarding issue)
tail_vm_log — Pull last 50 lines of error log

🔴 Advanced Workflows

4. The "Safety First" Update (Transactional Rollback)

Apply risky updates with a safety net:

flowchart TB A["snapshot_save"] --> B["start_download"] B --> C["wait_for_operation"] C --> D["exec_command"] D --> E{"check_vm_port"} E -->|"❌ Failed"| F["snapshot_restore"] E -->|"✅ Success"| G["snapshot_delete"]

snapshot_save — Create checkpoint "pre-update-v2"
start_download — Download new binary/patch
wait_for_operation — Block until complete
exec_command — Run installation script
check_vm_port — Verify service is back online
- IF FAILED: snapshot_restore to rollback
- IF SUCCESS: snapshot_delete to clean up

5. The "Resource Reclamation" (System Hygiene)

Identify and clean up orphaned Zombie VMs:

flowchart LR A["scan_system_health"] --> B["sequentialthinking"] B --> C["cleanup_zombies"] C --> D["get_vm_dashboard"]

scan_system_health — Identify Zombie VMs consuming resources
sequentialthinking — Analyze which are safe to delete
cleanup_zombies — Safely terminate with dry_run first
get_vm_dashboard — Confirm resources are freed

6. The "Deep Fix" Loop (Intelligent Debugging)

Autonomous diagnosis and repair of stuck processes:

flowchart TB A["get_vm_dashboard"] --> B["list_processes"] B --> C["grep_log_stream"] C --> D["sequentialthinking"] D --> E["kill_process"] E --> F["exec_with_sync"]

get_vm_dashboard — Detect CPU spike or stuck task
list_processes — Find the specific PID causing issues
grep_log_stream — Search logs for error signature
sequentialthinking — Formulate hypothesis
kill_process — Send SIGTERM to stuck process
exec_with_sync — Upload patched config and restart

💬 Example Prompts

Here are 30 natural language prompts with their corresponding tool calls:

1. Provision a New Database Server

"I need a fresh Redis server. Create a VM named 'redis-cache' using the 'hashicorp/bionic64' box."

{ "name": "create_vm", "arguments": { "name": "redis-cache", "box": "hashicorp/bionic64" } }

2. Status Check

"Is the 'frontend-react' VM currently running?"

{ "name": "get_vm_status", "arguments": { "name": "frontend-react" } }

3. Inventory Overview

"Show me a list of all the virtual machines we are currently managing."

{ "name": "list_vms", "arguments": {} }

4. Force Termination

"The 'experiment-01' VM is completely unresponsive. Destroy it immediately."

{ "name": "destroy_vm", "arguments": { "name": "experiment-01" } }

5. Idempotent Environment Check

"Ensure the 'integration-test' VM is running. If it's not there, create it."

{ "name": "ensure_dev_vm", "arguments": { "name": "integration-test" } }

6. Install Dependencies

"Run pip install -r requirements.txt inside the 'api-server' VM."

{ "name": "exec_command", "arguments": { "vm_name": "api-server", "command": "pip install -r requirements.txt" } }

7. Build and Sync

"Sync the latest changes to 'builder' and then run make build immediately."

{ "name": "exec_with_sync", "arguments": { "vm_name": "builder", "command": "make build" } }

8. Long-Running Job

"Start the data ingestion script (python ingest.py) on 'data-lake' in the background."

{ "name": "run_background_task", "arguments": { "vm_name": "data-lake", "command": "python ingest.py" } }

9. Deploy Configuration

"Upload my local .env.production file to /app/.env on the 'worker-node' VM."

{ "name": "upload_file", "arguments": { "vm_name": "worker-node", "source": ".env.production", "destination": "/app/.env" } }

10. Locate Error Logs

"Search for any files named error.log inside the /var/log directory."

{ "name": "search_files", "arguments": { "vm_name": "monitor", "query": "error.log", "path": "/var/log" } }

11. Setup File Watcher

"Configure a file sync. Map my local ./src folder to /usr/src/app on 'dev-main'."

{ "name": "configure_sync", "arguments": { "vm_name": "dev-main", "host_path": "./src", "guest_path": "/usr/src/app", "direction": "bidirectional" } }

12. Conflict Resolution

"There's a sync conflict on README.md. Use my local version."

{ "name": "resolve_conflict", "arguments": { "vm_name": "docs-site", "file_path": "README.md", "resolution": "use_host" } }

13. Live Debugging

"Show me the last 50 lines of the nginx error log on the 'proxy' VM."

{ "name": "tail_vm_log", "arguments": { "vm_name": "proxy", "path": "/var/log/nginx/error.log", "lines": 50 } }

14. Monitor Background Task

"What is the output so far for task task_12345?"

{ "name": "get_task_output", "arguments": { "vm_name": "data-lake", "task_id": "task_12345" } }

15. Search Logs

"Search the syslog on 'auth-service' for any 'segfault' errors."

{ "name": "grep_log_stream", "arguments": { "vm_name": "auth-service", "path": "/var/log/syslog", "pattern": "segfault" } }

16. Pre-Update Backup

"I'm about to upgrade the database. Save a snapshot called 'before-v14-upgrade'."

{ "name": "snapshot_save", "arguments": { "vm_name": "postgres-primary", "snapshot_name": "before-v14-upgrade" } }

17. Disaster Recovery

"The upgrade failed! Restore to the 'before-v14-upgrade' snapshot."

{ "name": "snapshot_restore", "arguments": { "vm_name": "postgres-primary", "snapshot_name": "before-v14-upgrade" } }

18. List Snapshots

"What snapshots are available for the 'kafka-broker' VM?"

{ "name": "snapshot_list", "arguments": { "vm_name": "kafka-broker" } }

19. Investigate High Load

"The 'ml-trainer' VM is slow. List the running processes."

{ "name": "list_processes", "arguments": { "vm_name": "ml-trainer" } }

20. Kill Stuck Process

"Process ID 9982 is stuck on 'worker-01'. Kill it."

{ "name": "kill_process", "arguments": { "vm_name": "worker-01", "pid": 9982, "signal": "SIGKILL" } }

21. Check Service Availability

"Is port 8080 open and listening on the 'jenkins' VM?"

{ "name": "check_vm_port", "arguments": { "vm_name": "jenkins", "guest_port": 8080 } }

22. System Health Dashboard

"Get me a full dashboard with CPU, RAM, and disk usage."

{ "name": "get_vm_dashboard", "arguments": { "vm_name": "production-replica" } }

23. Initiate Large Download

"Download the 10GB dataset from example.com to /data/ on the 'ai-model' VM."

{ "name": "start_download", "arguments": { "vm_name": "ai-model", "url": "http://example.com/data.tar.gz", "destination": "/data/data.tar.gz" } }

24. Blocking Wait

"Wait for the download operation op_5592 to finish."

{ "name": "wait_for_operation", "arguments": { "operation_id": "op_5592", "timeout_seconds": 600 } }

25. Detect Zombie VMs

"Scan the system to see if we have any orphaned Zombie VMs."

{ "name": "scan_system_health", "arguments": {} }

26. Clean Zombies (Dry Run)

"Check what would happen if we cleaned up 'zombie-1' and 'old-test'."

{ "name": "cleanup_zombies", "arguments": { "vm_names": ["zombie-1", "old-test"], "dry_run": true } }

⚙️ MCP Configuration

Claude Desktop / Cline / Cursor

Add to your claude_desktop_config.json or mcp_config.json:

{ "mcpServers": { "vagrant-mcp": { "command": "node", "args": ["C:\\path\\to\\Virtualbox-mcp-server\\apps\\mcp-server\\dist\\index.js"], "env": { "LOG_LEVEL": "info", "PATH": "C:\\Program Files (x86)\\Vagrant\\bin;C:\\Program Files\\Oracle\\VirtualBox;%PATH%" } } } }

🔥 Top 5 MCP Configuration Examples

1. Development Environment (Node.js + Docker)

{ "mcpServers": { "vagrant-mcp": { "command": "node", "args": ["/home/user/Virtualbox-mcp-server/apps/mcp-server/dist/index.js"], "env": { "LOG_LEVEL": "debug", "VAGRANT_HOME": "/home/user/.vagrant.d", "VM_DEFAULT_BOX": "ubuntu/jammy64", "VM_DEFAULT_MEMORY": "4096", "VM_DEFAULT_CPU": "4" } } } }

2. CI/CD Pipeline (Jenkins/GitHub Actions)

{ "mcpServers": { "vagrant-mcp": { "command": "node", "args": ["/opt/mcp/vagrant-mcp-server/dist/index.js"], "env": { "LOG_LEVEL": "warn", "VAGRANT_HOME": "/var/lib/jenkins/.vagrant.d", "VM_AUTO_DESTROY": "true", "VM_SNAPSHOT_BEFORE_TEST": "true" } } } }

3. Windows Workstation

{ "mcpServers": { "vagrant-mcp": { "command": "node.exe", "args": ["C:\\Users\\Developer\\mcp\\Virtualbox-mcp-server\\apps\\mcp-server\\dist\\index.js"], "env": { "LOG_LEVEL": "info", "PATH": "C:\\Program Files (x86)\\Vagrant\\bin;C:\\Program Files\\Oracle\\VirtualBox;C:\\Windows\\System32", "VAGRANT_HOME": "C:\\Users\\Developer\\.vagrant.d" } } } }

4. macOS with Homebrew

{ "mcpServers": { "vagrant-mcp": { "command": "/opt/homebrew/bin/node", "args": ["/Users/dev/Projects/Virtualbox-mcp-server/apps/mcp-server/dist/index.js"], "env": { "LOG_LEVEL": "info", "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin", "VAGRANT_HOME": "/Users/dev/.vagrant.d" } } } }

5. Production/Enterprise (Restricted Environment)

{ "mcpServers": { "vagrant-mcp": { "command": "node", "args": ["/srv/mcp/vagrant-server/dist/index.js"], "env": { "LOG_LEVEL": "error", "VAGRANT_HOME": "/srv/vagrant", "VM_MAX_COUNT": "10", "VM_ALLOWED_BOXES": "company/base-ubuntu,company/base-centos", "VM_REQUIRE_SNAPSHOT": "true", "GUARDRAILS_STRICT": "true" } } } }

🧪 Development

# Watch mode (rebuild on changes) npm run dev # Lint npm run lint # Format npm run format

📝 License

Made with ❤️ for AI-powered infrastructure management

⬆ Back to Top