rewrite README for PyPI with confident, direct style

- Bold opening: 94 tools, full VMware control
- Clear install instructions upfront
- Organized tool documentation with tables
- Real-world usage examples
- Streamlined configuration reference
This commit is contained in:
Ryan Malloy 2025-12-26 21:03:51 -07:00
parent eb59cd5e9a
commit 7843adede1

411
README.md
View File

@ -1,213 +1,135 @@
# mcvsphere # 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: Stop clicking through vSphere. Start talking to it.
> "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
```bash ```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 uvx mcvsphere
# Or install with pip # Or pip, if that's your thing
pip install mcvsphere pip install mcvsphere
``` ```
### Configuration Set your credentials:
Create a `.env` file or set environment variables:
```bash ```bash
VCENTER_HOST=vcenter.example.com export VCENTER_HOST=vcenter.example.com
VCENTER_USER=administrator@vsphere.local export VCENTER_USER=administrator@vsphere.local
VCENTER_PASSWORD=your-password export VCENTER_PASSWORD=your-password
VCENTER_INSECURE=true # Skip SSL verification (dev only)
``` ```
### Run the Server Add to Claude Code:
```bash ```bash
# Using uvx claude mcp add vsphere "uvx mcvsphere"
uvx mcvsphere
# Or if installed
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) ### VM Lifecycle
| Tool | Description | | Tool | What it does |
|------|-------------| |------|--------------|
| `list_vms` | List all virtual machines | | `create_vm` | Spin up new VMs from scratch |
| `get_vm_info` | Get detailed VM information | | `clone_vm` | Clone from templates or existing VMs |
| `create_vm` | Create a new virtual machine | | `delete_vm` | Clean removal |
| `clone_vm` | Clone from template or existing VM | | `reconfigure_vm` | Change CPU, memory, annotations |
| `delete_vm` | Delete a virtual machine | | `rename_vm` | Rename VMs |
| `reconfigure_vm` | Modify CPU, memory, annotation | | `list_vms` / `get_vm_info` | See everything |
| `rename_vm` | Rename a virtual machine |
### Power Operations (6 tools) ### Power Operations
| Tool | Description | `power_on_vm` | `power_off_vm` | `shutdown_guest` | `reboot_guest` | `suspend_vm` | `reset_vm`
|------|-------------|
| `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 |
### Snapshots (5 tools) ### Snapshots
| Tool | Description | `create_snapshot` | `revert_to_snapshot` | `delete_snapshot` | `delete_all_snapshots` | `list_snapshots`
|------|-------------|
| `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 |
### Guest Operations (7 tools) ### Guest Operations
*Requires VMware Tools running in the guest* *Run commands inside VMs. No SSH required.*
| Tool | Description | | Tool | What it does |
|------|-------------| |------|--------------|
| `list_guest_processes` | List processes in guest OS | | `run_command_in_guest` | Execute any command |
| `run_command_in_guest` | Execute command in guest | | `read_guest_file` | Pull files out |
| `read_guest_file` | Read file from guest OS | | `write_guest_file` | Push files in |
| `write_guest_file` | Write file to guest OS | | `list_guest_processes` | See what's running |
| `list_guest_directory` | List directory contents | | `list_guest_directory` | Browse the filesystem |
| `create_guest_directory` | Create directory in guest | | `create_guest_directory` | Make directories |
| `delete_guest_file` | Delete file or directory | | `delete_guest_file` | Clean up |
### Console & Monitoring (5 tools) ### Console & Monitoring
| Tool | Description | | Tool | What it does |
|------|-------------| |------|--------------|
| `vm_screenshot` | Capture VM console screenshot | | `vm_screenshot` | Capture the VM console |
| `wait_for_vm_tools` | Wait for VMware Tools to be ready | | `get_vm_stats` | Performance metrics |
| `get_vm_tools_status` | Get VMware Tools status | | `get_host_stats` | Host performance |
| `get_vm_stats` | Get VM performance statistics | | `wait_for_vm_tools` | Block until Tools ready |
| `get_host_stats` | Get host performance statistics | | `get_vm_tools_status` | Check Tools state |
### Serial Port Management (5 tools) ### Serial Console
*For network appliances and headless VMs* *For network appliances, headless boxes, and anything that talks over serial.*
| Tool | Description | `setup_serial_port` | `get_serial_port` | `connect_serial_port` | `clear_serial_port` | `remove_serial_port`
|------|-------------|
| `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 |
### Disk Management (5 tools) ### Disk Management
| Tool | Description | `add_disk` | `remove_disk` | `resize_disk` | `list_disks` | `get_disk_info`
|------|-------------|
| `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 |
### NIC Management (6 tools) ### Network Adapters
| Tool | Description | `add_nic` | `remove_nic` | `connect_nic` | `change_nic_network` | `list_nics` | `get_nic_info`
|------|-------------|
| `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 |
### OVF/OVA Management (5 tools) ### OVF/OVA Operations
| Tool | Description | `deploy_ovf` | `export_ovf` | `list_ovf_networks` | `upload_to_datastore` | `download_from_datastore`
|------|-------------|
| `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 |
### Host Management (10 tools) ### Host Management
| Tool | Description | `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`
|------|-------------|
| `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 |
### Datastore & Resources (8 tools) ### Datastore & Resources
| Tool | Description | `get_datastore_info` | `browse_datastore` | `get_vcenter_info` | `get_resource_pool_info` | `get_network_info` | `list_templates` | `get_alarms` | `get_recent_events`
|------|-------------|
| `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 |
### vCenter Operations (18 tools) ### vCenter Operations
*Available when connected to vCenter Server* *Full cluster and organizational control.*
| Tool | Description | `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`
|------|-------------|
| `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 |
## 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://vms` | All virtual machines |
| `esxi://hosts` | All ESXi hosts | | `esxi://hosts` | All ESXi hosts |
| `esxi://datastores` | All datastores | | `esxi://datastores` | All datastores |
@ -215,36 +137,57 @@ Access real-time data through MCP resources:
| `esxi://clusters` | All clusters | | `esxi://clusters` | All clusters |
| `esxi://resource-pools` | All resource pools | | `esxi://resource-pools` | All resource pools |
## Architecture ---
The server uses a modular mixin architecture: ## Real Examples
### Rapid VM Deployment
``` ```
mcvsphere/ You: Create a VM called "test-web" with 4 CPUs, 8GB RAM, 100GB disk
├── server.py # FastMCP server setup
├── connection.py # VMware connection management Claude: VM 'test-web' created. Want me to power it on?
├── config.py # Settings and configuration
└── mixins/ You: Yes, and take a screenshot once it's at the BIOS
├── vm_lifecycle.py # VM CRUD operations
├── power_ops.py # Power management Claude: [powers on, waits, captures screenshot]
├── snapshots.py # Snapshot management Here's the console - it's at the boot menu.
├── 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
``` ```
## 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 | | Variable | Description | Default |
|----------|-------------|---------| |----------|-------------|---------|
| `VCENTER_HOST` | vCenter/ESXi hostname or IP | *required* | | `VCENTER_HOST` | vCenter or ESXi hostname | *required* |
| `VCENTER_USER` | Username | *required* | | `VCENTER_USER` | Username | *required* |
| `VCENTER_PASSWORD` | Password | *required* | | `VCENTER_PASSWORD` | Password | *required* |
| `VCENTER_INSECURE` | Skip SSL verification | `false` | | `VCENTER_INSECURE` | Skip SSL verification | `false` |
@ -252,63 +195,22 @@ mcvsphere/
| `VCENTER_CLUSTER` | Target cluster | *auto-detect* | | `VCENTER_CLUSTER` | Target cluster | *auto-detect* |
| `VCENTER_DATASTORE` | Default datastore | *auto-detect* | | `VCENTER_DATASTORE` | Default datastore | *auto-detect* |
| `VCENTER_NETWORK` | Default network | *auto-detect* | | `VCENTER_NETWORK` | Default network | *auto-detect* |
| `MCP_TRANSPORT` | Transport mode (`stdio` or `sse`) | `stdio` | | `MCP_TRANSPORT` | `stdio` or `sse` | `stdio` |
| `LOG_LEVEL` | Logging level | `INFO` | | `LOG_LEVEL` | Logging verbosity | `INFO` |
## Docker Support ---
## Docker
```bash ```bash
# Build
docker build -t mcvsphere .
# Run
docker run -d \ docker run -d \
-e VCENTER_HOST=vcenter.example.com \ -e VCENTER_HOST=vcenter.example.com \
-e VCENTER_USER=admin@vsphere.local \ -e VCENTER_USER=admin@vsphere.local \
-e VCENTER_PASSWORD=secret \ -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 ## Requirements
@ -316,30 +218,19 @@ telnet://10.20.0.22:4521
- VMware vSphere 7.0+ (ESXi or vCenter) - VMware vSphere 7.0+ (ESXi or vCenter)
- VMware Tools (for guest operations) - VMware Tools (for guest operations)
## Development ---
```bash ## Built With
# Clone the repo
git clone https://github.com/yourusername/mcvsphere.git
cd mcvsphere
# Install dependencies - [FastMCP](https://github.com/jlowin/fastmcp) - MCP server framework
uv sync - [pyVmomi](https://github.com/vmware/pyvmomi) - VMware vSphere API
# Run tests ---
uv run python test_client.py
```
## License ## 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. **94 tools. Your entire VMware infrastructure. Controlled by conversation.**
## 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