Virtualbox Server

Бесплатно

A Model Context Protocol server for managing Virtualbox and Vagrant virtual machines via a TypeScript interface. It enables users to programmatically create new

автор: usemanusai

GitHub

Описание

A Model Context Protocol server for managing Virtualbox and Vagrant virtual machines via a TypeScript interface. It enables users to programmatically create new VMs and monitor their status through simple JSON-RPC tools.

README

TypeScript MCP SDK NPM Version 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

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

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:

Workflow: ensure_dev_vm → sync_to_vm → install_dev_tools → 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:

Workflow: start_download → wait_for_operation → 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:

Workflow: list_vms → check_vm_port → 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:

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

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:

Workflow: scan_system_health → sequentialthinking → cleanup_zombies → 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:

Workflow: get_vm_dashboard → list_processes → grep_log_stream → sequentialthinking → kill_process → 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:

VM Lifecycle Examples

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

Execution Examples

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

File Operations Examples

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

Observability Examples

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

Snapshot Examples

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

Process Control Examples

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

Network & Dashboard Examples

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

Progress & Download Examples

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

System Maintenance Examples

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

MIT © usemanusai

Made with ❤️ for AI-powered infrastructure management

⬆ Back to Top

from github.com/usemanusai/Virtualbox-mcp-server

Как установить

Добавь это в claude_desktop_config.json и перезапусти Claude Desktop.

{
  "mcpServers": {
    "virtualbox-mcp-server": {
      "command": "npx",
      "args": []
    }
  }
}

Virtualbox Server

Бесплатно

A Model Context Protocol server for managing Virtualbox and Vagrant virtual machines via a TypeScript interface. It enables users to programmatically create new

автор: usemanusai

GitHub

Описание

README

TypeScript MCP SDK NPM Version 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

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

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:

Workflow: ensure_dev_vm → sync_to_vm → install_dev_tools → 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:

Workflow: start_download → wait_for_operation → 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:

Workflow: list_vms → check_vm_port → 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:

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

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:

Workflow: scan_system_health → sequentialthinking → cleanup_zombies → 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:

Workflow: get_vm_dashboard → list_processes → grep_log_stream → sequentialthinking → kill_process → 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:

VM Lifecycle Examples

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

Execution Examples

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

File Operations Examples

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

Observability Examples

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

Snapshot Examples

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

Process Control Examples

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

Network & Dashboard Examples

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

Progress & Download Examples

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

System Maintenance Examples

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

from github.com/usemanusai/Virtualbox-mcp-server

Как установить

Добавь это в claude_desktop_config.json и перезапусти Claude Desktop.

{
  "mcpServers": {
    "virtualbox-mcp-server": {
      "command": "npx",
      "args": []
    }
  }
}

Command Palette

Virtualbox Server

Описание

README

✨ Features

📦 Architecture

🚀 Quick Start

Prerequisites

Installation

Running the Server

🛠️ 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)

2. The "Dataset Fetch" (Async Download)

3. The "Service Pulse" (Basic Debugging)

🔴 Advanced Workflows

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

5. The "Resource Reclamation" (System Hygiene)

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

💬 Example Prompts

1. Provision a New Database Server

2. Status Check

3. Inventory Overview

4. Force Termination

5. Idempotent Environment Check

6. Install Dependencies

7. Build and Sync

8. Long-Running Job

9. Deploy Configuration

10. Locate Error Logs

11. Setup File Watcher

12. Conflict Resolution

13. Live Debugging

14. Monitor Background Task

15. Search Logs

16. Pre-Update Backup

17. Disaster Recovery

18. List Snapshots

19. Investigate High Load

20. Kill Stuck Process

21. Check Service Availability

22. System Health Dashboard

23. Initiate Large Download

24. Blocking Wait

25. Detect Zombie VMs

26. Clean Zombies (Dry Run)

⚙️ MCP Configuration

Claude Desktop / Cline / Cursor

🔥 Top 5 MCP Configuration Examples

1. Development Environment (Node.js + Docker)

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

3. Windows Workstation

4. macOS with Homebrew

5. Production/Enterprise (Restricted Environment)

🧪 Development

📝 License

Как установить

Похожие MCP

GitHub

Supabase

Everything

Filesystem

Virtualbox Server

Описание

README

✨ Features

📦 Architecture