MCP/mcvsphere
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

rewrite README for PyPI with confident, direct style

Browse Source 
- 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
1 changed files with 151 additions and 260 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

411
README.md
View File

@ -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.**