mcvsphere

A comprehensive VMware vSphere management server implementing the Model Context Protocol (MCP), enabling AI assistants like Claude to manage virtual infrastructure through natural language.

Why mcvsphere?

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

# Install with uv (recommended)
uvx mcvsphere

# Or install with pip
pip install mcvsphere

Configuration

Create a .env file or set environment variables:

VCENTER_HOST=vcenter.example.com
VCENTER_USER=administrator@vsphere.local
VCENTER_PASSWORD=your-password
VCENTER_INSECURE=true  # Skip SSL verification (dev only)

Run the Server

# Using uvx
uvx mcvsphere

# Or if installed
mcvsphere

Add to Claude Code

claude mcp add esxi "uvx mcvsphere"

Available Tools (94 Total)

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

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

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

Guest Operations (7 tools)

Requires VMware Tools running in the guest

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

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

Serial Port Management (5 tools)

For network appliances and headless VMs

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

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

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

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

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

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

vCenter Operations (18 tools)

Available when connected to vCenter Server

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

MCP Resources

Access real-time data through MCP resources:

Resource URI	Description
esxi://vms	All virtual machines
esxi://hosts	All ESXi hosts
esxi://datastores	All datastores
esxi://networks	All networks
esxi://clusters	All clusters
esxi://resource-pools	All resource pools

Architecture

The server uses a modular mixin architecture:

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

Configuration Options

Variable	Description	Default
VCENTER_HOST	vCenter/ESXi hostname or IP	required
VCENTER_USER	Username	required
VCENTER_PASSWORD	Password	required
VCENTER_INSECURE	Skip SSL verification	false
VCENTER_DATACENTER	Target datacenter	auto-detect
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

Docker Support

# 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

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

• Python 3.11+
• VMware vSphere 7.0+ (ESXi or vCenter)
• VMware Tools (for guest operations)

Development

# Clone the repo
git clone https://github.com/yourusername/mcvsphere.git
cd mcvsphere

# Install dependencies
uv sync

# Run tests
uv run python test_client.py

License

MIT License - See LICENSE for details.

Contributing

Contributions welcome! Please read the contributing guidelines and submit a PR.

Acknowledgments

• Built with FastMCP
• Uses pyVmomi for vSphere API
• Inspired by the Model Context Protocol specification