Virtualbox Server

✨ 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

🚀 Quick Start

Prerequisites

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

Installation

# 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

Running the Server

# Run the installed server
virtualbox-mcp-server

# Or run from source
node apps/mcp-server/dist/index.js

🛠️ All 38 Tools

VM Lifecycle (6 tools)

Execution (3 tools)

Environment Setup (3 tools)

File Operations (7 tools)

👁️ Observability (3 tools)

📸 Snapshots (4 tools)

⚙️ Process Control (2 tools)

🌐 Network (1 tool)

📊 Dashboard (1 tool)

⏳ Progress Awareness (5 tools)

🛡️ Guardrails & Maintenance (2 tools)

🧠 AI Reasoning (1 tool)

🔄 Architectural Workflows

🟢 Easy Workflows

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

🔴 Advanced Workflows

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:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

MIT © usemanusai