🖥️ VirtualBox MCP Server

---

✨ Features

- 46 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 (46 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

$3

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

$3

`bash

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
`

$3

`bash

Run the installed server

virtualbox-mcp-server

Or run from source

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

---

🛠️ All 46 Tools

$3

| 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) |
| resize_vm_resources | Modify CPU/RAM/GUI settings |
| package_box | Export VM as a .box file |
| set_display_mode | Toggle Headless/GUI mode |

$3

| 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 |
| atomic_transaction_exec | Execute with auto-rollback on failure |

$3

| 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 |
| inject_secrets | Securely inject environment variables |

$3

| 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 |

$3

| 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 |

$3

| 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 |

$3

| Tool | Description |
|------|-------------|
| list_processes | Return structured list of running processes (ps aux) |
| kill_process | Send SIGTERM/SIGKILL to a process |

$3

| Tool | Description |
|------|-------------|
| check_vm_port | Verify if port is listening in VM & accessible from host |

$3

| Tool | Description |
|------|-------------|
| get_vm_dashboard | Comprehensive dashboard: CPU, RAM, Disk, tasks, logs |

$3

| 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 |
| sentinel_await | Wait for file, port, or service condition |

$3

| Tool | Description |
|------|-------------|
| scan_system_health | Check disk/memory, identify Zombie VMs |
| cleanup_zombies | Safely destroy orphaned VMs (with dry-run option) |
| audit_security | Scan for open ports and weak configs |
| forensic_blackbox_capture | Capture process & network state |

$3

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

---

🔄 Architectural Workflows

$3

#### 1. The "Daily Standup" (Environment Prep)

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

Workflow: ensure_dev_vm → sync_to_vm → install_dev_tools → get_vm_dashboard

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

#### 2. The "Dataset Fetch" (Async Download)

Download large files without blocking:

Workflow: start_download → wait_for_operation → search_files

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

#### 3. The "Service Pulse" (Basic Debugging)

Quickly diagnose why localhost:8080 isn't loading:

Workflow: list_vms → check_vm_port → tail_vm_log

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

---

$3

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

Apply risky updates with a safety net:

Workflow: snapshot_save → start_download → check_vm_port → (rollback or delete snapshot)

1. snapshot_save — Create checkpoint "pre-update-v2"
2. start_download — Download new binary/patch
3. wait_for_operation — Block until complete
4. exec_command — Run installation script
5. 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:

Workflow: scan_system_health → sequentialthinking → cleanup_zombies → get_vm_dashboard

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

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

Autonomous diagnosis and repair of stuck processes:

Workflow: get_vm_dashboard → list_processes → grep_log_stream → sequentialthinking → kill_process → exec_with_sync

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

---

💬 Example Prompts

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

VM Lifecycle Examples

$3

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

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

$3

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

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

$3

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

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

$3

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

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

$3

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

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







Execution Examples

$3

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

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

$3

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

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

$3

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

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







File Operations Examples

$3

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

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

$3

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

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

$3

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

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

$3

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

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







Observability Examples

$3

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

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

$3

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

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

$3

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

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







Snapshot Examples

$3

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

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

$3

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

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

$3

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

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







Process Control Examples

$3

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

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

$3

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

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







Network & Dashboard Examples

$3

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

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

$3

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

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







Progress & Download Examples

$3

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

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

$3

> "Wait for the download operation op_5592 to finish."

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







System Maintenance Examples

$3

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

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

$3

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

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



---

⚙️ MCP Configuration

$3

Add to your claude_desktop_config.json or mcp_config.json:

`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%"
}
}
}
}
`

$3

#### 1. Development Environment (Node.js + Docker)

`json
{
"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)

`json
{
"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

`json
{
"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

`json
{
"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)

`json
{
"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

`bash

Watch mode (rebuild on changes)

npm run dev

Lint

npm run lint

Format

npm run format
``

---

📝 License

MIT © usemanusai

---