Ryan Malloy eb59cd5e9a rename project: esxi-mcp-server → mcvsphere

mcvsphere = Model Control for vSphere

Updates:
- Package renamed from esxi_mcp_server to mcvsphere
- CLI entry point: mcvsphere (was esxi-mcp-server)
- All imports and references updated
- Docker configs updated
- Test suites updated

2025-12-26 20:58:48 -07:00

10 KiB

Raw Blame History

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

10 KiB Raw Blame History