# 🖥️ VirtualBox MCP Server
<div align="center">
[](https://www.typescriptlang.org/)
[](https://modelcontextprotocol.io/)
[](LICENSE)
[](https://turbo.build/)
**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](#-features) • [Quick Start](#-quick-start) • [Tools](#-all-38-tools) • [Workflows](#-architectural-workflows) • [Examples](#-example-prompts) • [Configuration](#%EF%B8%8F-mcp-configuration)
</div>
---
## ✨ 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
```
```mermaid
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
```bash
# 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
```bash
# 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:
```mermaid
flowchart LR
A["ensure_dev_vm"] --> B["sync_to_vm"]
B --> C["install_dev_tools"]
C --> D["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:
```mermaid
flowchart LR
A["start_download"] --> B["wait_for_operation"]
B --> C["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:
```mermaid
flowchart LR
A["list_vms"] --> B["check_vm_port"]
B --> C["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:
```mermaid
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"]
```
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:
```mermaid
flowchart LR
A["scan_system_health"] --> B["sequentialthinking"]
B --> C["cleanup_zombies"]
C --> D["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:
```mermaid
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"]
```
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:
<details>
<summary><strong>VM Lifecycle Examples</strong></summary>
### 1. Provision a New Database Server
> "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"
}
}
```
### 2. Status Check
> "Is the 'frontend-react' VM currently running?"
```json
{
"name": "get_vm_status",
"arguments": {
"name": "frontend-react"
}
}
```
### 3. Inventory Overview
> "Show me a list of all the virtual machines we are currently managing."
```json
{
"name": "list_vms",
"arguments": {}
}
```
### 4. Force Termination
> "The 'experiment-01' VM is completely unresponsive. Destroy it immediately."
```json
{
"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."
```json
{
"name": "ensure_dev_vm",
"arguments": {
"name": "integration-test"
}
}
```
</details>
<details>
<summary><strong>Execution Examples</strong></summary>
### 6. Install Dependencies
> "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"
}
}
```
### 7. Build and Sync
> "Sync the latest changes to 'builder' and then run `make build` immediately."
```json
{
"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."
```json
{
"name": "run_background_task",
"arguments": {
"vm_name": "data-lake",
"command": "python ingest.py"
}
}
```
</details>
<details>
<summary><strong>File Operations Examples</strong></summary>
### 9. Deploy Configuration
> "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"
}
}
```
### 10. Locate Error Logs
> "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"
}
}
```
### 11. Setup File Watcher
> "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"
}
}
```
### 12. Conflict Resolution
> "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"
}
}
```
</details>
<details>
<summary><strong>Observability Examples</strong></summary>
### 13. Live Debugging
> "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
}
}
```
### 14. Monitor Background Task
> "What is the output so far for task `task_12345`?"
```json
{
"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."
```json
{
"name": "grep_log_stream",
"arguments": {
"vm_name": "auth-service",
"path": "/var/log/syslog",
"pattern": "segfault"
}
}
```
</details>
<details>
<summary><strong>Snapshot Examples</strong></summary>
### 16. Pre-Update Backup
> "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"
}
}
```
### 17. Disaster Recovery
> "The upgrade failed! Restore to the 'before-v14-upgrade' snapshot."
```json
{
"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?"
```json
{
"name": "snapshot_list",
"arguments": {
"vm_name": "kafka-broker"
}
}
```
</details>
<details>
<summary><strong>Process Control Examples</strong></summary>
### 19. Investigate High Load
> "The 'ml-trainer' VM is slow. List the running processes."
```json
{
"name": "list_processes",
"arguments": {
"vm_name": "ml-trainer"
}
}
```
### 20. Kill Stuck Process
> "Process ID 9982 is stuck on 'worker-01'. Kill it."
```json
{
"name": "kill_process",
"arguments": {
"vm_name": "worker-01",
"pid": 9982,
"signal": "SIGKILL"
}
}
```
</details>
<details>
<summary><strong>Network & Dashboard Examples</strong></summary>
### 21. Check Service Availability
> "Is port 8080 open and listening on the 'jenkins' VM?"
```json
{
"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."
```json
{
"name": "get_vm_dashboard",
"arguments": {
"vm_name": "production-replica"
}
}
```
</details>
<details>
<summary><strong>Progress & Download Examples</strong></summary>
### 23. Initiate Large Download
> "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"
}
}
```
### 24. Blocking Wait
> "Wait for the download operation `op_5592` to finish."
```json
{
"name": "wait_for_operation",
"arguments": {
"operation_id": "op_5592",
"timeout_seconds": 600
}
}
```
</details>
<details>
<summary><strong>System Maintenance Examples</strong></summary>
### 25. Detect Zombie VMs
> "Scan the system to see if we have any orphaned Zombie VMs."
```json
{
"name": "scan_system_health",
"arguments": {}
}
```
### 26. Clean Zombies (Dry Run)
> "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
}
}
```
</details>
---
## ⚙️ MCP Configuration
### Claude Desktop / Cline / Cursor
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%"
}
}
}
}
```
### 🔥 Top 5 MCP Configuration Examples
#### 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](https://github.com/usemanusai)
---
<div align="center">
**Made with ❤️ for AI-powered infrastructure management**
[⬆ Back to Top](#%EF%B8%8F-virtualbox-mcp-server)
</div>
