diff --git a/README.md b/README.md index f91113b..3900bc7 100644 --- a/README.md +++ b/README.md @@ -1,213 +1,135 @@ # mcvsphere -A comprehensive VMware vSphere management server implementing the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), enabling AI assistants like Claude to manage virtual infrastructure through natural language. +**94 tools. Full VMware control. Natural language.** -## Why mcvsphere? +[![PyPI version](https://img.shields.io/pypi/v/mcvsphere.svg)](https://pypi.org/project/mcvsphere/) +[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/) +[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT) -Traditional VMware management requires navigating complex UIs or writing scripts. With mcvsphere, you can simply ask: - -> "Create a new VM with 4 CPUs and 8GB RAM, then take a snapshot before installing the OS" - -And watch it happen. The server exposes **94 tools** covering every aspect of vSphere management. - -## Features - -- **94 MCP Tools** - Complete vSphere management capabilities -- **6 MCP Resources** - Real-time access to VMs, hosts, datastores, networks, and clusters -- **Modular Architecture** - 13 specialized mixins organized by function -- **Full vCenter & ESXi Support** - Works with standalone hosts or vCenter Server -- **Guest Operations** - Execute commands, transfer files inside VMs via VMware Tools -- **Serial Console Access** - Network serial ports for headless VMs and network appliances -- **VM Screenshots** - Capture console screenshots for monitoring or documentation - -## Quick Start - -### Installation +Stop clicking through vSphere. Start talking to it. ```bash -# Install with uv (recommended) +uvx mcvsphere +``` + +--- + +## What is this? + +mcvsphere is an MCP server that gives AI assistants like Claude complete control over your VMware infrastructure. Create VMs, manage snapshots, run commands inside guests, take console screenshots, configure network appliances - all through conversation. + +**94 MCP tools.** Not a toy demo. Not "just the basics." The whole thing. + +``` +You: "Spin up a new VM with 4 CPUs and 16GB RAM, clone it twice, + then snapshot all three before I start testing" + +Claude: Done. Three VMs running, all snapshotted. What's next? +``` + +--- + +## Install in 30 Seconds + +```bash +# One command uvx mcvsphere -# Or install with pip +# Or pip, if that's your thing pip install mcvsphere ``` -### Configuration - -Create a `.env` file or set environment variables: +Set your credentials: ```bash -VCENTER_HOST=vcenter.example.com -VCENTER_USER=administrator@vsphere.local -VCENTER_PASSWORD=your-password -VCENTER_INSECURE=true # Skip SSL verification (dev only) +export VCENTER_HOST=vcenter.example.com +export VCENTER_USER=administrator@vsphere.local +export VCENTER_PASSWORD=your-password ``` -### Run the Server +Add to Claude Code: ```bash -# Using uvx -uvx mcvsphere - -# Or if installed -mcvsphere +claude mcp add vsphere "uvx mcvsphere" ``` -### Add to Claude Code +That's it. You're managing vSphere with AI now. -```bash -claude mcp add esxi "uvx mcvsphere" -``` +--- -## Available Tools (94 Total) +## The Full Arsenal: 94 Tools -### VM Lifecycle (6 tools) -| Tool | Description | -|------|-------------| -| `list_vms` | List all virtual machines | -| `get_vm_info` | Get detailed VM information | -| `create_vm` | Create a new virtual machine | -| `clone_vm` | Clone from template or existing VM | -| `delete_vm` | Delete a virtual machine | -| `reconfigure_vm` | Modify CPU, memory, annotation | -| `rename_vm` | Rename a virtual machine | +### VM Lifecycle +| Tool | What it does | +|------|--------------| +| `create_vm` | Spin up new VMs from scratch | +| `clone_vm` | Clone from templates or existing VMs | +| `delete_vm` | Clean removal | +| `reconfigure_vm` | Change CPU, memory, annotations | +| `rename_vm` | Rename VMs | +| `list_vms` / `get_vm_info` | See everything | -### Power Operations (6 tools) -| Tool | Description | -|------|-------------| -| `power_on_vm` | Power on a VM | -| `power_off_vm` | Power off a VM (hard) | -| `shutdown_guest` | Graceful guest OS shutdown | -| `reboot_guest` | Graceful guest OS reboot | -| `suspend_vm` | Suspend a VM | -| `reset_vm` | Hard reset a VM | +### Power Operations +`power_on_vm` | `power_off_vm` | `shutdown_guest` | `reboot_guest` | `suspend_vm` | `reset_vm` -### Snapshots (5 tools) -| Tool | Description | -|------|-------------| -| `list_snapshots` | List all snapshots | -| `create_snapshot` | Create a new snapshot | -| `revert_to_snapshot` | Revert to a snapshot | -| `delete_snapshot` | Delete a snapshot | -| `delete_all_snapshots` | Remove all snapshots | +### Snapshots +`create_snapshot` | `revert_to_snapshot` | `delete_snapshot` | `delete_all_snapshots` | `list_snapshots` -### Guest Operations (7 tools) -*Requires VMware Tools running in the guest* +### Guest Operations +*Run commands inside VMs. No SSH required.* -| Tool | Description | -|------|-------------| -| `list_guest_processes` | List processes in guest OS | -| `run_command_in_guest` | Execute command in guest | -| `read_guest_file` | Read file from guest OS | -| `write_guest_file` | Write file to guest OS | -| `list_guest_directory` | List directory contents | -| `create_guest_directory` | Create directory in guest | -| `delete_guest_file` | Delete file or directory | +| Tool | What it does | +|------|--------------| +| `run_command_in_guest` | Execute any command | +| `read_guest_file` | Pull files out | +| `write_guest_file` | Push files in | +| `list_guest_processes` | See what's running | +| `list_guest_directory` | Browse the filesystem | +| `create_guest_directory` | Make directories | +| `delete_guest_file` | Clean up | -### Console & Monitoring (5 tools) -| Tool | Description | -|------|-------------| -| `vm_screenshot` | Capture VM console screenshot | -| `wait_for_vm_tools` | Wait for VMware Tools to be ready | -| `get_vm_tools_status` | Get VMware Tools status | -| `get_vm_stats` | Get VM performance statistics | -| `get_host_stats` | Get host performance statistics | +### Console & Monitoring +| Tool | What it does | +|------|--------------| +| `vm_screenshot` | Capture the VM console | +| `get_vm_stats` | Performance metrics | +| `get_host_stats` | Host performance | +| `wait_for_vm_tools` | Block until Tools ready | +| `get_vm_tools_status` | Check Tools state | -### Serial Port Management (5 tools) -*For network appliances and headless VMs* +### Serial Console +*For network appliances, headless boxes, and anything that talks over serial.* -| Tool | Description | -|------|-------------| -| `get_serial_port` | Get serial port configuration | -| `setup_serial_port` | Configure network serial port | -| `connect_serial_port` | Connect/disconnect serial port | -| `clear_serial_port` | Reset serial port connection | -| `remove_serial_port` | Remove serial port from VM | +`setup_serial_port` | `get_serial_port` | `connect_serial_port` | `clear_serial_port` | `remove_serial_port` -### Disk Management (5 tools) -| Tool | Description | -|------|-------------| -| `list_disks` | List VM disks | -| `add_disk` | Add a new disk | -| `remove_disk` | Remove a disk | -| `resize_disk` | Expand disk size | -| `get_disk_info` | Get disk details | +### Disk Management +`add_disk` | `remove_disk` | `resize_disk` | `list_disks` | `get_disk_info` -### NIC Management (6 tools) -| Tool | Description | -|------|-------------| -| `list_nics` | List VM network adapters | -| `add_nic` | Add a network adapter | -| `remove_nic` | Remove a network adapter | -| `connect_nic` | Connect/disconnect NIC | -| `change_nic_network` | Change NIC network | -| `get_nic_info` | Get NIC details | +### Network Adapters +`add_nic` | `remove_nic` | `connect_nic` | `change_nic_network` | `list_nics` | `get_nic_info` -### OVF/OVA Management (5 tools) -| Tool | Description | -|------|-------------| -| `deploy_ovf` | Deploy VM from OVF template | -| `export_ovf` | Export VM to OVF | -| `list_ovf_networks` | List OVF network mappings | -| `upload_to_datastore` | Upload file to datastore | -| `download_from_datastore` | Download file from datastore | +### OVF/OVA Operations +`deploy_ovf` | `export_ovf` | `list_ovf_networks` | `upload_to_datastore` | `download_from_datastore` -### Host Management (10 tools) -| Tool | Description | -|------|-------------| -| `list_hosts` | List ESXi hosts | -| `get_host_info` | Get host details | -| `get_host_hardware` | Get hardware information | -| `get_host_networking` | Get network configuration | -| `list_services` | List host services | -| `get_service_status` | Get service status | -| `start_service` | Start a host service | -| `stop_service` | Stop a host service | -| `restart_service` | Restart a host service | -| `get_ntp_config` | Get NTP configuration | +### Host Management +`list_hosts` | `get_host_info` | `get_host_hardware` | `get_host_networking` | `list_services` | `get_service_status` | `start_service` | `stop_service` | `restart_service` | `get_ntp_config` -### Datastore & Resources (8 tools) -| Tool | Description | -|------|-------------| -| `get_datastore_info` | Get datastore details | -| `browse_datastore` | Browse datastore files | -| `get_vcenter_info` | Get vCenter information | -| `get_resource_pool_info` | Get resource pool details | -| `get_network_info` | Get network details | -| `list_templates` | List VM templates | -| `get_alarms` | Get active alarms | -| `get_recent_events` | Get recent events | +### Datastore & Resources +`get_datastore_info` | `browse_datastore` | `get_vcenter_info` | `get_resource_pool_info` | `get_network_info` | `list_templates` | `get_alarms` | `get_recent_events` -### vCenter Operations (18 tools) -*Available when connected to vCenter Server* +### vCenter Operations +*Full cluster and organizational control.* -| Tool | Description | -|------|-------------| -| `list_folders` | List VM folders | -| `create_folder` | Create a folder | -| `delete_folder` | Delete a folder | -| `move_vm_to_folder` | Move VM to folder | -| `list_clusters` | List clusters | -| `get_cluster_info` | Get cluster details | -| `list_resource_pools` | List resource pools | -| `create_resource_pool` | Create resource pool | -| `delete_resource_pool` | Delete resource pool | -| `move_vm_to_resource_pool` | Move VM to resource pool | -| `list_tags` | List tags | -| `get_vm_tags` | Get tags on a VM | -| `apply_tag_to_vm` | Apply tag to VM | -| `remove_tag_from_vm` | Remove tag from VM | -| `migrate_vm` | Migrate VM to another host | -| `list_recent_tasks` | List recent tasks | -| `list_recent_events` | List recent events | -| `cancel_task` | Cancel a running task | +`list_folders` | `create_folder` | `delete_folder` | `move_vm_to_folder` | `list_clusters` | `get_cluster_info` | `list_resource_pools` | `create_resource_pool` | `delete_resource_pool` | `move_vm_to_resource_pool` | `list_tags` | `get_vm_tags` | `apply_tag_to_vm` | `remove_tag_from_vm` | `migrate_vm` | `list_recent_tasks` | `list_recent_events` | `cancel_task` -## MCP Resources +--- -Access real-time data through MCP resources: +## 6 MCP Resources -| Resource URI | Description | -|--------------|-------------| +Real-time data, always current: + +| Resource | Data | +|----------|------| | `esxi://vms` | All virtual machines | | `esxi://hosts` | All ESXi hosts | | `esxi://datastores` | All datastores | @@ -215,36 +137,57 @@ Access real-time data through MCP resources: | `esxi://clusters` | All clusters | | `esxi://resource-pools` | All resource pools | -## Architecture +--- -The server uses a modular mixin architecture: +## Real Examples + +### Rapid VM Deployment ``` -mcvsphere/ -├── server.py # FastMCP server setup -├── connection.py # VMware connection management -├── config.py # Settings and configuration -└── mixins/ - ├── vm_lifecycle.py # VM CRUD operations - ├── power_ops.py # Power management - ├── snapshots.py # Snapshot management - ├── guest_ops.py # Guest OS operations - ├── console.py # Screenshots & Tools monitoring - ├── serial_port.py # Serial console access - ├── disk_management.py # Disk operations - ├── nic_management.py # Network adapter operations - ├── ovf_management.py # OVF/OVA handling - ├── host_management.py # Host operations - ├── monitoring.py # Performance monitoring - ├── resources.py # MCP resources - └── vcenter_ops.py # vCenter-specific operations +You: Create a VM called "test-web" with 4 CPUs, 8GB RAM, 100GB disk + +Claude: VM 'test-web' created. Want me to power it on? + +You: Yes, and take a screenshot once it's at the BIOS + +Claude: [powers on, waits, captures screenshot] + Here's the console - it's at the boot menu. ``` -## Configuration Options +### Guest Operations Without SSH + +``` +You: What's the uptime on linux-server? + +Claude: [runs "uptime" inside the guest via VMware Tools] + linux-server has been up for 47 days, 3:22 +``` + +### Serial Console for Network Gear + +``` +You: I need console access to my Cisco router VM + +Claude: [configures network serial port] + Done. Connect via: telnet://10.20.0.22:4521 +``` + +### Disaster Recovery Practice + +``` +You: Snapshot all production VMs before I run the update + +Claude: [snapshots 12 VMs in parallel] + All 12 production VMs snapshotted. Ready when you are. +``` + +--- + +## Configuration | Variable | Description | Default | |----------|-------------|---------| -| `VCENTER_HOST` | vCenter/ESXi hostname or IP | *required* | +| `VCENTER_HOST` | vCenter or ESXi hostname | *required* | | `VCENTER_USER` | Username | *required* | | `VCENTER_PASSWORD` | Password | *required* | | `VCENTER_INSECURE` | Skip SSL verification | `false` | @@ -252,63 +195,22 @@ mcvsphere/ | `VCENTER_CLUSTER` | Target cluster | *auto-detect* | | `VCENTER_DATASTORE` | Default datastore | *auto-detect* | | `VCENTER_NETWORK` | Default network | *auto-detect* | -| `MCP_TRANSPORT` | Transport mode (`stdio` or `sse`) | `stdio` | -| `LOG_LEVEL` | Logging level | `INFO` | +| `MCP_TRANSPORT` | `stdio` or `sse` | `stdio` | +| `LOG_LEVEL` | Logging verbosity | `INFO` | -## Docker Support +--- + +## Docker ```bash -# Build -docker build -t mcvsphere . - -# Run docker run -d \ -e VCENTER_HOST=vcenter.example.com \ -e VCENTER_USER=admin@vsphere.local \ -e VCENTER_PASSWORD=secret \ - mcvsphere + ghcr.io/supportedsystems/mcvsphere:latest ``` -## Examples - -### Create a VM and Install an OS - -``` -User: Create a new VM called "web-server" with 4 CPUs, 8GB RAM, and a 100GB disk - -Claude: I'll create that VM for you. -[Calls create_vm with name="web-server", cpu=4, memory_mb=8192, disk_gb=100] - -VM 'web-server' created successfully. - -User: Power it on and take a screenshot - -Claude: [Calls power_on_vm, then vm_screenshot] - -The VM is now running. Here's the console screenshot showing the BIOS boot screen. -``` - -### Guest Operations - -``` -User: Run "uname -a" on the linux-server VM - -Claude: [Calls run_command_in_guest with command="/usr/bin/uname", arguments="-a"] - -The command returned: -Linux linux-server 5.15.0-generic #1 SMP x86_64 GNU/Linux -``` - -### Serial Console for Network Appliances - -``` -User: Set up a serial console on my Cisco router VM - -Claude: [Calls setup_serial_port with name="cisco-router", protocol="telnet"] - -Serial port configured. You can connect via: -telnet://10.20.0.22:4521 -``` +--- ## Requirements @@ -316,30 +218,19 @@ telnet://10.20.0.22:4521 - VMware vSphere 7.0+ (ESXi or vCenter) - VMware Tools (for guest operations) -## Development +--- -```bash -# Clone the repo -git clone https://github.com/yourusername/mcvsphere.git -cd mcvsphere +## Built With -# Install dependencies -uv sync +- [FastMCP](https://github.com/jlowin/fastmcp) - MCP server framework +- [pyVmomi](https://github.com/vmware/pyvmomi) - VMware vSphere API -# Run tests -uv run python test_client.py -``` +--- ## License -MIT License - See [LICENSE](LICENSE) for details. +MIT - do whatever you want with it. -## Contributing +--- -Contributions welcome! Please read the contributing guidelines and submit a PR. - -## Acknowledgments - -- Built with [FastMCP](https://github.com/jlowin/fastmcp) -- Uses [pyVmomi](https://github.com/vmware/pyvmomi) for vSphere API -- Inspired by the Model Context Protocol specification +**94 tools. Your entire VMware infrastructure. Controlled by conversation.**