Virtualization MCP
VirtualBox management MCP server with comprehensive VM operations, networking, storage, snapshots, and security features. Built with FastMCP 2.12+ for Claude Desktop integration.
Ask AI about Virtualization MCP
Powered by Claude Β· Grounded in docs
I know everything about Virtualization MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
virtualization-mcp - Professional VirtualBox Management for Claude Desktop
v1.0.1b2 - Production-ready VirtualBox MCP server with comprehensive VM operations
β Production Ready: Full-featured VirtualBox management through Claude Desktop with 60+ operations organized in 5 intuitive tools!
π What is virtualization-mcp?
virtualization-mcp is a professional Model Context Protocol (MCP) server that brings comprehensive VirtualBox management directly to Claude Desktop. Manage virtual machines using natural language - create, start, stop, snapshot, configure networking, and more!
β¨ Key Highlights
- π― 5 Portmanteau Tools - Clean, organized interface with 60+ operations
- π Switchable Modes - Production (5 tools) or Testing (60+ tools)
- π 100% Documented - Comprehensive docstrings for every operation
- π§ͺ 499 Passing Tests - Robust test suite with 82.5% success rate
- π¦ 296 KB MCPB - Optimized package, no bundled dependencies
- π¨ 8 AI Prompts - 25+ KB of guidance templates
- β‘ FastMCP 2.12+ - Latest MCP framework
- π Cross-Platform - Windows, macOS, Linux support
π¦ Installation
For Claude Desktop (Recommended)
-
Download MCPB Package:
- Go to Releases
- Download
virtualization-mcp-{version}.mcpb
-
Install in Claude Desktop:
- Open Claude Desktop
- Go to Settings β Extensions
- Drag and drop the
.mcpbfile - Restart Claude Desktop
-
Start Managing VMs:
"List all my virtual machines" "Create a new Ubuntu VM with 4GB RAM" "Take a snapshot of my-vm"
For Python / Development
# From GitHub release
pip install https://github.com/sandraschi/virtualization-mcp/releases/download/v1.0.1b2/virtualization_mcp-1.0.1b2-py3-none-any.whl
# Or from git
pip install git+https://github.com/sandraschi/virtualization-mcp.git
# Or for development
git clone https://github.com/sandraschi/virtualization-mcp.git
cd virtualization-mcp
uv sync --dev
Prerequisites
- VirtualBox 7.0+ installed and in PATH
- Python 3.10+ (for manual installation)
- Claude Desktop (for MCPB installation)
π― Features
VM Lifecycle Management
- Create VMs from templates or custom configurations
- Start, stop, pause, resume, reset VMs
- Clone VMs (full or linked clones)
- Delete VMs with optional disk cleanup
- Get detailed VM information and metrics
Storage Management
- Create virtual disks (VDI, VMDK, VHD formats)
- Attach/detach storage devices
- Manage storage controllers (IDE, SATA, SCSI, NVMe)
- Configure disk properties and settings
- Shared folder management
Network Configuration
- Configure network adapters (NAT, Bridged, Host-only, Internal)
- Set up port forwarding rules
- Manage host-only networks
- Advanced network adapter configuration
Snapshot Management
- Create snapshots with descriptions
- List all snapshots for a VM
- Restore VMs to previous snapshots
- Delete individual snapshots
- Snapshot-based cloning
System Information
- Host system information
- VirtualBox version details
- Available OS types
- VM performance metrics
- Screenshot capture
π οΈ Tool Modes
Production Mode (Default) - 6-7 Tools
Clean, organized interface perfect for daily use:
- vm_management - Complete VM lifecycle (10 operations)
- network_management - Network configuration (5 operations)
- snapshot_management - Snapshot operations (4 operations)
- storage_management - Storage & disk management (6 operations)
- system_management - System info & diagnostics (5 operations)
- discovery_management - Help & tool info (4 operations)
- hyperv_management - Hyper-V VMs (4 operations, Windows only)
Total: 33 operations in 6 tools (7 on Windows)
Note: discovery_management is app-specific help (NOT the same as MCP protocol's native tools/list)
Testing Mode - 60+ Tools
All individual functions plus portmanteau tools for development and debugging.
Switch modes in mcp_config.json:
{
"env": {
"TOOL_MODE": "production" // or "testing"
}
}
See Tool Mode Configuration for details.
π‘ Usage Examples
Basic VM Management
User: "List all my VMs"
Claude: Uses vm_management(action="list")
User: "Create a Ubuntu development VM"
Claude: Uses vm_management(action="create", vm_name="ubuntu-dev",
os_type="Ubuntu_64", memory_mb=4096, disk_size_gb=50)
User: "Start the VM ubuntu-dev"
Claude: Uses vm_management(action="start", vm_name="ubuntu-dev")
Snapshot Workflow
User: "Create a snapshot of ubuntu-dev called 'clean-state'"
Claude: Uses snapshot_management(action="create", vm_name="ubuntu-dev",
snapshot_name="clean-state")
User: "List all snapshots for ubuntu-dev"
Claude: Uses snapshot_management(action="list", vm_name="ubuntu-dev")
User: "Restore ubuntu-dev to the clean-state snapshot"
Claude: Uses snapshot_management(action="restore", vm_name="ubuntu-dev",
snapshot_name="clean-state")
Network Configuration
User: "Set up NAT networking on my VM"
Claude: Uses network_management(action="configure_adapter",
vm_name="my-vm", adapter_slot=0, network_type="nat")
User: "Create a host-only network called dev-network"
Claude: Uses network_management(action="create_network",
network_name="dev-network")
π Documentation
Quick Start
- Quick Start Guide - Get started in 5 minutes
- Claude Desktop Setup - Integration guide
Technical Documentation
- Tool Mode Configuration - Switch between modes
- FastMCP 2.12 Compliance - Integration details
- Docstring Coverage - 100% coverage report
- Project Status - Complete status
MCPB Packaging
- MCPB Building Guide - Package creation
- Implementation Summary - Technical details
User Guides
- VM Management - VM operations
- Network Configuration - Networking
- Snapshot Management - Snapshots
- Storage Management - Disks & storage
π¨ AI Prompt Templates
8 comprehensive templates included (25+ KB total):
- backup-strategies.md - Backup and disaster recovery patterns
- complete-scenarios.md - Full deployment scenarios
- network-configuration.md - Network setup guides
- security-best-practices.md - Security hardening
- snapshot-management.md - Snapshot strategies
- storage-optimization.md - Storage configuration
- vm-deployment-strategies.md - Deployment patterns (345 lines!)
- vm-templates.md - Template usage and customization
ποΈ Architecture
Built With:
- FastMCP 2.12.4 - Latest MCP framework
- UV - Modern Python package manager
- Ruff - Fast Python linter & formatter
- pytest - Comprehensive test suite
- VirtualBox 7.0+ - Virtualization platform
Tool Organization:
- Portmanteau Tools - Action-based consolidated operations
- Individual Tools - Direct function access (testing mode)
- Service Layer - Business logic and validation
- VBox Adapter - VirtualBox integration
- Plugin System - Extensible architecture
π§ͺ Testing
Run Tests:
# Install development dependencies
uv sync --dev
# Run all tests
uv run pytest
# Run with coverage
uv run pytest --cov=virtualization_mcp --cov-report=term-missing
Test Statistics:
- Total Tests: 605
- Passing: 499 (82.5%)
- Coverage: 39% β Target: 80% (GLAMA Gold Standard)
- Integration Tests: VBox-aware (mocked when unavailable)
π§ Configuration
Basic Setup (Claude Desktop):
{
"mcpServers": {
"virtualization-mcp": {
"command": "uv",
"args": [
"--directory",
"/path/to/virtualization-mcp",
"run",
"virtualization-mcp"
],
"env": {
"TOOL_MODE": "production",
"LOG_LEVEL": "INFO"
}
}
}
}
Advanced Configuration:
See .env.example for all available settings:
- Tool mode selection
- VirtualBox path configuration
- Logging levels
- Timeouts and limits
- Default VM settings
- Feature flags
π€ Contributing
We welcome contributions! Please see:
- Contributing Guidelines - How to contribute
- Security Policy - Security considerations
- Troubleshooting - Common issues
Development Setup:
# Clone repository
git clone https://github.com/sandraschi/virtualization-mcp.git
cd virtualization-mcp
# Install with UV
uv sync --dev
# Run tests
uv run pytest
# Run linting
uv run ruff check .
π Project Status
- β Production Ready - v1.0.1b2 released
- β Quality - 0 linting errors, 499 tests passing
- β Documentation - 100% docstring coverage
- β MCPB Packaged - Optimized for Claude Desktop
- β FastMCP Compliant - Version 2.12.4
- β Clean Repository - Professional organization
See Project Status for complete details.
π Roadmap & Extensions
Coming Soon
- VM Templates: Pre-built configurations for Ubuntu, Windows, macOS
- Advanced Monitoring: Real-time performance metrics and health checks
- Security Features: Vulnerability scanning and access control
- Enhanced Networking: Visual topology mapping and advanced port management
Planned Features
- Plugin System: Extensible architecture for custom functionality
- Cloud Integration: AWS/Azure VM synchronization
- CI/CD Support: Jenkins/GitHub Actions integration
- Interactive CLI: Direct command-line interface
Quick Wins
- β Progress tracking for long operations
- β Health check endpoints
- β Configuration validation tools
- β Operation history and audit logging
See Extensions & Improvements Guide for detailed roadmap.
π Links
- Repository: https://github.com/sandraschi/virtualization-mcp
- Releases: https://github.com/sandraschi/virtualization-mcp/releases
- Issues: https://github.com/sandraschi/virtualization-mcp/issues
- Latest Release: v1.0.1b2
π§ Contact
Author: Sandra Schi
Email: sandraschipal@protonmail.com
GitHub: @sandraschi
π License
This project is licensed under the MIT License - see the LICENSE file for details.
π Quick Start
- Download
.mcpbfrom releases - Drop into Claude Desktop
- Ask: "What can you do with VirtualBox?"
- Start managing VMs with natural language!
Manage VirtualBox VMs effortlessly through Claude Desktop! π
