vboxmcp by sandraschi - MCP Server

VirtualBox MCP Server

v1.0.0 - FastMCP 2.12+ compliant VirtualBox management server with full MCP client support

✅ Production Ready: VBoxMCP is now fully functional and ready for production use with Claude Desktop and other MCP clients!

🚀 Overview

VirtualBox MCP Server (vboxmcp) is a FastMCP 2.12+ compliant server that provides comprehensive management of VirtualBox virtual machines through a standardized MCP interface. This production-ready release offers complete VM lifecycle management, advanced features, and seamless integration with Claude Desktop.

✨ Key Features

Complete VM Lifecycle Management: Create, start, stop, pause, resume, reset, and delete VMs with simple commands
Advanced Storage Management: Handle disks, ISOs, and storage controllers with ease
Snapshot Management: Take, restore, delete, and manage VM snapshots for testing workflows
Network Configuration: Set up NAT, Bridged, Host-Only, and Internal networks
Resource Allocation: Configure CPU, memory, and storage resources
Cross-Platform: Works on Windows, Linux, and macOS (with VirtualBox 7.0+ support)
Secure: Sandboxed operations with proper access controls
Extensible: Plugin architecture for custom functionality
MCP 2.12+ Compatible: Full support for MCP tool discovery and invocation
Comprehensive API: Programmatic access to all VirtualBox features
Claude Desktop Ready: Tested and verified to work with Claude Desktop
Production Ready: Stable, reliable, and ready for daily use

🆕 Latest Updates (v1.0.0)

✅ Server Startup Fixed

Resolved Import Issues: Fixed relative import problems that prevented server startup
FastMCP Compatibility: Updated to work with FastMCP 2.12.2+ API
AsyncIO Management: Fixed event loop conflicts for proper server operation
Tool Registration: Simplified and optimized tool registration system
Claude Desktop Integration: Verified working integration with Claude Desktop

🔧 Technical Improvements

Simplified Tool API: Removed deprecated parameters and streamlined tool definitions
Better Error Handling: Comprehensive error handling with clear messages
Plugin System: Enhanced plugin architecture with Hyper-V and Windows Sandbox support
Configuration Management: Improved configuration system with environment variables
Logging System: Enhanced logging with proper levels and formatting

📚 Documentation

For detailed documentation, please visit our documentation site.

📖 Quick Start

🛠️ Using with Claude Desktop

Install VBoxMCP:
```
pip install vboxmcp
```

Configure Claude Desktop: Add the following to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "vboxmcp": {
      "command": "python",
      "args": ["-m", "vboxmcp"],
      "env": {
        "PYTHONPATH": "src",
        "VBOX_INSTALL_PATH": "C:\\Program Files\\Oracle\\VirtualBox",
        "VBOX_USER_HOME": "%USERPROFILE%\\VirtualBox VMs",
        "DEBUG": "true"
      }
    }
  }
}

Start Managing VMs: Use natural language commands in Claude Desktop:

"List all my virtual machines"
"Create a new Ubuntu VM with 4GB RAM and 2 CPUs"
"Start the VM named 'ubuntu-dev'"
"Take a snapshot of 'ubuntu-dev' called 'clean-install'"

🛠️ Using FastMCP Inspector (Development)

Install FastMCP if you haven't already:
```
pip install fastmcp
```

Start the inspector with your MCP server:

# From the project root
fastmcp dev src/vboxmcp/all_tools_server.py

Open the web interface at http://127.0.0.1:6274 to test and debug your MCP tools
For detailed documentation, see the

Quick Links

- Set up and run your first VM
- Complete list of available commands
- Interactive tool testing and debugging
- Practical examples and use cases
- Detailed API documentation
- Contribute to the project

🛠️ Features in Detail

Virtual Machine Management

Create, clone, and delete VMs
Start, stop, pause, and resume VMs
Configure VM settings (CPU, memory, firmware, etc.)
Manage VM groups and folders

Storage Management

Create and manage virtual disks (VDI, VMDK, VHD, RAW)
Attach/detach disks to/from VMs
Mount/unmount ISO images
Manage storage controllers (SATA, SCSI, IDE, SAS)
Resize and clone disks
Snapshot disk states

Network Management

Configure network adapters (NAT, NAT Network, Bridged, Host-Only, Internal)
Set up port forwarding
Configure network bandwidth limits
Manage DHCP servers

Advanced Features

Manage VM snapshots (create, restore, delete, list)
Configure shared folders
Set up shared clipboard and drag-and-drop
Configure audio and video settings
Manage USB devices

🚀 Quick Start

Prerequisites

Python 3.8 or higher
VirtualBox 7.0 or higher (with Extension Pack recommended)
VirtualBox Python SDK (will be installed automatically)
Git (for source installation)

Installation

Option 1: Install from PyPI (Recommended)

pip install vboxmcp

Option 2: Install from Source

# Clone the repository
git clone https://github.com/sandraschi/vboxmcp.git
cd vboxmcp

# Install in development mode with all dependencies
pip install -e .[dev]

Basic Usage

Start the MCP server:
```
python -m vboxmcp
```
Use with Claude Desktop:
- Add the MCP configuration to Claude Desktop
- Start managing your VMs with natural language commands

Example commands:

"List all my virtual machines"
"Create a new Ubuntu VM with 4GB RAM and 2 CPUs"
"Start the VM named 'ubuntu-dev'"
"Take a snapshot of 'ubuntu-dev' called 'clean-install'"

Server Status

✅ Server Status: Fully operational and ready for production use

All tools registered successfully
Plugins initialized (Hyper-V Manager, Windows Sandbox Helper)
FastMCP 2.12.2+ compatibility verified
Claude Desktop integration tested and working

📖 Documentation

Getting Started

Core Concepts

Advanced Topics

Examples

🛠️ Available Tools

VM Management

list_vms: List all available VirtualBox VMs
get_vm_info: Get detailed information about a VM
start_vm: Start a virtual machine
stop_vm: Stop a running virtual machine
create_vm: Create a new virtual machine
delete_vm: Delete a virtual machine
clone_vm: Clone a virtual machine
reset_vm: Reset a virtual machine
pause_vm: Pause a virtual machine
resume_vm: Resume a paused virtual machine

Storage Management

list_storage_controllers: List storage controllers for a VM
create_storage_controller: Create a storage controller for a VM
remove_storage_controller: Remove a storage controller from a VM

Network Management

list_hostonly_networks: List all host-only networks
create_hostonly_network: Create a host-only network
remove_hostonly_network: Remove a host-only network

Snapshot Management

list_snapshots: List snapshots for a VM
create_snapshot: Create a snapshot of a VM
restore_snapshot: Restore a VM to a snapshot
delete_snapshot: Delete a snapshot

System Information

get_system_info: Get system information
get_vbox_version: Get VirtualBox version information
list_ostypes: List available OS types

Example Tools

example_greet: A simple example tool that greets someone
get_counter: Get the current counter value
analyze_file: Analyze a file for potential malware

Backup Tools

create_vm_backup: Create a backup of a virtual machine
list_vm_backups: List all VM backups
delete_vm_backup: Delete a VM backup

Monitoring Tools

record_api_request: Record an API request for metrics
record_error: Record an error for metrics
update_vm_metrics: Update VM-specific metrics
update_system_metrics: Update system-wide metrics

Security Tools

run_security_scan: Run a security scan on the specified target
get_security_test_status: Get the status of a security test

Malware Analysis Tools

get_analysis: Get the results of a malware analysis
list_analyses: List all malware analyses with optional filtering
delete_analysis: Delete a malware analysis and associated files
list_quarantine: List all files in quarantine

🔧 Troubleshooting

Common Issues

Server won't start

Error: ImportError: attempted relative import with no known parent package
Solution: Ensure PYTHONPATH is set to 'src' in your MCP configuration

VBoxManage not found

Error: VBoxManage command not found
Solution: Add VirtualBox to PATH or set VBOX_INSTALL_PATH environment variable

FastMCP compatibility issues

Error: FastMCP.tool() got an unexpected keyword argument
Solution: Update to FastMCP 2.12.2+ and ensure proper tool registration

Claude Desktop connection issues

Error: Server not responding
Solution: Check MCP configuration JSON and ensure server is running

Getting Help

GitHub Issues: Report bugs and request features
Documentation: Complete documentation
Discussions: Community discussions

🤝 Contributing

Contributions are welcome! Please see our for details on how to contribute to this project.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

FastMCP - For the MCP server framework
VirtualBox - For the powerful virtualization platform
Python - For being awesome

📬 Contact

For questions and support, please open an issue on our GitHub repository.

📊 Project Status

✅ Production Ready: VBoxMCP v1.0.0 is fully functional and ready for production use

✅ Server startup issues resolved
✅ FastMCP 2.12.2+ compatibility verified
✅ Claude Desktop integration working
✅ All core tools operational
✅ Plugin system functional

🔗 Related Projects

FastMCP - The MCP server framework
VirtualBox - The virtualization platform
Claude Desktop - MCP client for natural language interaction

Built with Austrian efficiency for practical VirtualBox automation through Claude Desktop. 🚀

Ready for production deployment in minutes, not hours.