vSphere MCP Server
README.md
# vSphere MCP Server
A comprehensive Model Context Protocol (MCP) server for VMware vSphere management, providing AI agents with full access to virtual infrastructure operations through a secure, Dockerized environment.
## Features
### Core VM Management
- **List VMs** - Get all virtual machines with power states
- **VM Details** - Detailed information about specific VMs
- **Power Operations** - Start, stop, restart VMs
- **Resource Monitoring** - CPU, RAM, and network utilization
- **Storage Information** - Disk usage and datastore details
### Advanced Operations
- **Snapshot Management** - Create, list, delete and **revert** VM snapshots
- **Template Management** - List and manage VM templates
- **Bulk Operations** - Power operations on multiple VMs
- **Resource Modification** - Change CPU and memory allocation
- **Network Management** - Port groups and network configuration
- **VM Cloning** - Clone templates into new VMs via pyVmomi
### Monitoring & Reporting
- **Performance Monitoring** - Real-time resource utilization
- **Event Logging** - VM events and system logs
- **Alarm Management** - Active alarms and alerts
- **Comprehensive Reports** - Environment-wide analytics
- **Resource Utilization** - CPU, memory, and storage summaries
### Safety Features
- **Confirmation System** - All destructive operations require explicit confirmation
- **Optional Bearer Token Auth** - Restrict access to `/mcp` with `MCP_AUTH_TOKEN`
- **Tool Allow-Listing** - Hide any tool from clients with `DISABLED_TOOLS` (e.g. read-only deployments)
- **Error Handling** - Comprehensive error messages and troubleshooting
- **Secure Authentication** - Environment-based credential management
- **Audit Trail** - Clear logging of all operations
## Installation
### Prerequisites
- Docker and Docker Compose
- VMware vCenter Server 7.x / 8.x
- Valid vCenter credentials
### Quick Start
1. **Clone repo**
2. **Configure Environment**
```bash
cp env.example .env
# Edit .env with your vCenter credentials
```
3. **Deploy with Docker**
```bash
docker compose up -d
```
## Configuration
### Environment Variables
Create a `.env` file with the following variables:
```env
# vCenter Connection
VCENTER_HOST=vcenter.domain.local
VCENTER_USER=username@domain.local
VCENTER_PASSWORD=your_password_here
INSECURE=True
# Server Configuration
SERVER_HOST=0.0.0.0
SERVER_PORT=8000
# MCP Server Authentication (optional, leave empty to disable auth)
MCP_AUTH_TOKEN=
# Tools to hide from clients (optional, comma-separated tool names)
DISABLED_TOOLS=
```
> `.env` is excluded from both git (`.gitignore`) and the image build (`.dockerignore`).
> Credentials are injected at runtime via `env_file`, never baked into the image layer.
### API Transport
Two different vSphere APIs are used depending on the operation:
| API | Used for | Client |
|-----|----------|--------|
| vSphere REST (`/api`) | VM listing, power, inventory, performance | `vsphere_client.py` |
| vSphere SOAP (pyVmomi) | Snapshots, cloning, templates, network lookup | `soap_client.py`, `pyvmomi_client.py` |
Snapshot operations use SOAP because **vSphere 8 removed the REST snapshot endpoints**.
### AnythingLLM Integration
Add the following configuration to your `anythingllm_mcp_servers.json`. When
`MCP_AUTH_TOKEN` is set, the same value must be supplied as `auth_token`:
```json
{
"mcpServers": {
"vsphere-mcp-server": {
"name": "vSphere MCP Server",
"type": "streamable",
"url": "http://vsphere-mcp-server:8000/mcp",
"auth_token": null,
"enabled": true
}
}
}
```
### Local stdio (Claude Desktop, etc.)
For MCP clients that launch the server as a local subprocess over stdio
(e.g. Claude Desktop) instead of connecting to an HTTP endpoint, set
`MCP_TRANSPORT=stdio` and provide vCenter credentials directly in the
client's own server config — stdio mode has no `.env` file and no
interactive credential prompt, so `VCENTER_HOST`/`VCENTER_USER`/
`VCENTER_PASSWORD` must be set here or the server exits immediately with
an error.
```json
{
"mcpServers": {
"vsphere-mcp-server": {
"command": "python",
"args": ["-m", "vsphere_mcp_server.server"],
"env": {
"PYTHONPATH": "src",
"MCP_TRANSPORT": "stdio",
"VCENTER_HOST": "vcenter.domain.local",
"VCENTER_USER": "username@domain.local",
"VCENTER_PASSWORD": "your_password_here",
"INSECURE": "True"
}
}
}
}
```
This path runs directly against a local Python install (`pip install -r
requirements.txt` first) — it does not use Docker. The Docker/AnythingLLM
streamable-HTTP setup above is unaffected and remains the recommended
deployment for production use.
## Available Tools
42 tools are exposed. `hostname` is optional everywhere and falls back to
`VCENTER_HOST`.
### VM Management
| Tool | Description | Parameters |
|------|-------------|------------|
| `list_vms` | List all virtual machines | `hostname` |
| `get_vm_details` | Get detailed VM information | `vm_id`, `hostname` |
| `power_on_vm` | Power on a virtual machine | `vm_id`, `hostname` |
| `power_off_vm` | Power off a virtual machine | `vm_id`, `hostname` |
### Infrastructure Management
| Tool | Description | Parameters |
|------|-------------|------------|
| `list_hosts` | List all ESXi hosts | `hostname` |
| `get_host_details` | Get ESXi host details | `host_id`, `hostname` |
| `list_datacenters` | List all datacenters | `hostname` |
| `get_datacenter_details` | Get datacenter details | `datacenter_id`, `hostname` |
| `list_datastores` | List all datastores | `hostname` |
| `get_datastore_details` | Get datastore details | `datastore_id`, `hostname` |
| `list_folders` | List inventory folders | `folder_type`, `hostname` |
| `get_folder_details` | Get folder details | `folder_id`, `hostname` |
| `list_networks` | List all networks | `hostname` |
| `get_network_details` | Get network details | `network_id`, `hostname` |
| `list_vlans` | Extract VLANs from network names | `hostname` |
| `get_vlan_info` | Look up a VLAN by name or ID | `vlan_query`, `hostname` |
| `get_port_groups` | Get network port groups | `hostname` |
### Monitoring & Performance
| Tool | Description | Parameters |
|------|-------------|------------|
| `get_vm_performance_info` | Get VM performance metrics | `hostname` |
| `get_host_performance_info` | Get host performance metrics | `hostname` |
| `get_vm_disk_usage` | Get VM disk utilization | `hostname` |
| `get_vm_storage_info` | Get VM storage layout | `hostname` |
| `get_datastore_usage` | Get datastore utilization | `hostname` |
| `get_vms_with_high_resource_usage` | Find VMs with high resource allocation | `hostname` |
| `get_vm_events` | Get VM events | `vm_id`, `hostname` |
| `get_alarms` | Get active alarms | `hostname` |
### Snapshot Management
Snapshot tools use the SOAP API (vSphere 8 removed the REST endpoints).
| Tool | Description | Parameters |
|------|-------------|------------|
| `list_vm_snapshots` | List one VM's snapshots, or query all VMs' snapshots | `vm_id` (optional; omit for fleet-wide query), `hostname` (optional) |
| `create_vm_snapshot` | Create VM snapshot | `vm_id`, `snapshot_name`, `description`, `hostname` (optional) |
| `delete_vm_snapshot` | Delete VM snapshot | `vm_id`, `snapshot_id`, `confirm`, `hostname` (optional) |
### Template Management
| Tool | Description | Parameters |
|------|-------------|------------|
| `list_templates` | List VM templates (REST) | `hostname` |
| `find_template_pyvmomi` | Find a template via pyVmomi | `name`, `datacenter`, `hostname` |
### pyVmomi Operations (clone & networks)
| Tool | Description | Parameters |
|------|-------------|------------|
| `list_datacenters_pyvmomi` | List datacenters via pyVmomi | `hostname` |
| `list_clusters_pyvmomi` | List clusters | `datacenter`, `hostname` |
| `clone_vm` | Clone a template into a new VM | `vm_name`, `template_name`, `cluster_name`, `datastore_name`, `network_name`, `target_datacenter`, `cpu_count`, `memory_gb`, `confirm`, `hostname` |
| `get_vm_networks_pyvmomi` | Get a VM's networks | `vm_name`, `hostname` |
### Reporting & Analytics
| Tool | Description | Parameters |
|------|-------------|------------|
| `generate_vm_report` | Generate comprehensive VM report | `hostname` |
| `get_resource_utilization_summary` | Get resource utilization summary | `hostname` |
### Automation
| Tool | Description | Parameters |
|------|-------------|------------|
| `bulk_power_operations` | Bulk power operations | `operation`, `vm_list`, `hostname` |
| `bulk_delete_vms` | Bulk delete VMs | `vm_list`, `confirm`, `hostname` |
### Destructive Operations (Require Confirmation)
| Tool | Description | Parameters |
|------|-------------|------------|
| `delete_vm` | Delete virtual machine | `vm_id`, `confirm`, `hostname` |
| `modify_vm_resources` | Modify VM resources | `vm_id`, `cpu_count`, `memory_gb`, `confirm`, `hostname` |
| `force_power_off_vm` | Force power off VM | `vm_id`, `confirm`, `hostname` |
| `delete_vm_snapshot` | Delete a snapshot | `vm_id`, `snapshot_name`, `confirm`, `hostname` |
| `revert_vm_snapshot` | Revert to a snapshot | `vm_id`, `snapshot_name`, `confirm`, `hostname` |
| `clone_vm` | Clone a template | see above |
**Destructive operations require explicit confirmation by setting `confirm=True`**
## Filtering, counting, and ranking
The list tools (`list_vms`, `list_hosts`, `list_datastores`, `list_networks`,
`list_clusters_pyvmomi`) accept optional `filters`, `group_by`, `fields`,
`sort_by`/`descending`, and `limit` parameters. Filtering, counting, and
sorting run inside the server (one PropertyCollector round-trip for the whole
inventory), so only the result — never the full inventory — reaches the LLM.
`list_vm_snapshots` supports the same parameters in fleet mode: called
without `vm_id`, it queries the snapshots of every VM in one round-trip.
Examples:
- Which VMs run hardware version vmx-13?
`list_vms(filters=[{"field": "hardware_version", "op": "eq", "value": "vmx-13"}])`
- Show the guest OS distribution:
`list_vms(group_by="guest_os")` → one line per OS with count and percentage
- Datastores below 10% free:
`list_datastores(filters=[{"field": "free_pct", "op": "lt", "value": 10}])`
- VMs with hardware version vmx-13 or older:
`list_vms(filters=[{"field": "hardware_version", "op": "lte", "value": "vmx-13"}])`
- The 10 largest VMs by provisioned storage:
`list_vms(sort_by="storage_provisioned_gb", fields=["name", "storage_provisioned_gb"], limit=10)`
- The 10 oldest snapshots anywhere in the fleet:
`list_vm_snapshots(sort_by="age_days", limit=10)`
- Snapshots older than 30 days, per VM:
`list_vm_snapshots(filters=[{"field": "age_days", "op": "gt", "value": 30}], group_by="vm_name")`
- Which VMs are in which network?
`list_vms(fields=["name", "networks"], limit=0)` — or
`list_vms(group_by="networks")` for the VM count per portgroup
- VMs attached to any DMZ portgroup:
`list_vms(filters=[{"field": "networks", "op": "contains", "value": "DMZ"}])`
- VMs stored on a specific datastore:
`list_vms(filters=[{"field": "datastores", "op": "eq", "value": "prod_store"}])`
- Hosts mounting fewer than two datastores:
`list_hosts(filters=[{"field": "datastore_count", "op": "lt", "value": 2}])`
Operators: `eq, ne, contains, not_contains, gt, gte, lt, lte, in` (conditions
are ANDed, string matching is case-insensitive). Range operators compare
numbers, and also prefix-number strings like `vmx-13` by their trailing
number. `sort_by` orders by any queryable field (`descending` defaults to
true — biggest/latest first). Each tool's description lists its queryable
fields. `limit` defaults to 50 rows (`0` = unlimited).
Membership fields: VMs, hosts, and clusters expose `networks` and
`datastores` (name lists, resolved in one bulk lookup) plus
`network_count`/`datastore_count`. On these list fields `eq`/`contains`
match if ANY member matches, `ne`/`not_contains` only if NO member does,
and `group_by` counts an object once per member (a multi-homed VM appears
under every network it is attached to; objects with no members fall under
`(none)`).
## Security Features
### Confirmation System
All destructive operations require explicit confirmation:
```python
# First call - shows warning
delete_vm(vm_id="MyServer", confirm=False)
# Returns: DESTRUCTIVE OPERATION: Delete VM MyServer...
# Second call - executes operation
delete_vm(vm_id="MyServer", confirm=True)
# Returns: VM MyServer deleted successfully
```
### Bearer Token Authentication
Set `MCP_AUTH_TOKEN` to require `Authorization: Bearer <token>` on every
request to `/mcp`. Requests with a missing or wrong token get `401`. Leave the
variable empty to disable authentication.
```bash
curl -X POST http://127.0.0.1:8000/mcp \
-H "Authorization: Bearer $MCP_AUTH_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}'
```
### Disabling Tools
List tool names in `DISABLED_TOOLS` (comma-separated) to keep them from being
registered at all: clients never see them in the tool list and cannot call
them. Unknown names are reported on stderr at startup, so a typo does not
silently leave a tool enabled.
Read-only deployment (every tool that changes vSphere state):
```env
DISABLED_TOOLS=power_on_vm,power_off_vm,force_power_off_vm,bulk_power_operations,create_vm_snapshot,delete_vm_snapshot,revert_vm_snapshot,delete_vm,bulk_delete_vms,modify_vm_resources,clone_vm
```
Only block the destructive ones:
```env
DISABLED_TOOLS=delete_vm,bulk_delete_vms,delete_vm_snapshot,revert_vm_snapshot,force_power_off_vm,modify_vm_resources,bulk_power_operations
```
### Environment-Based Authentication
- Credentials stored in environment variables
- No hardcoded passwords
- Secure Docker deployment
- SSL/TLS support with configurable verification
## Usage Examples
### Basic VM Operations
```bash
# List all VMs
"Show me all virtual machines"
# Get VM details
"Get details for VM WebServer01"
# Power operations
"Power on the VM DatabaseServer"
```
### Monitoring and Reporting
```bash
# Performance monitoring
"Show me CPU and memory usage for all VMs"
"Which VMs have high resource usage?"
# Storage monitoring
"Show me datastore usage"
"Which VMs have disk usage over 90%?"
# Comprehensive reporting
"Generate a complete report of the vSphere environment"
```
### Snapshot Management
```bash
# Create snapshots
"Create a snapshot of VM WebServer01 before updates"
# List snapshots
"Show me all snapshots for VM DatabaseServer"
# Revert to a snapshot (requires confirmation)
"Revert VM WebServer01 to snapshot 'before-upgrade'"
# -> shows warning, no action
"Revert VM WebServer01 to snapshot 'before-upgrade' with confirmation"
# -> VM is powered off first (if running), then reverted; stays powered off
```
`revert_vm_snapshot` behaviour:
1. Without `confirm=True` it only returns a warning and touches nothing.
2. A running or suspended VM is powered off first; if powering off fails the
revert is aborted.
3. The revert uses `suppressPowerOn=True`, so the VM is left **powered off**
afterwards and must be powered on manually.
### Destructive Operations (with confirmation)
```bash
# VM deletion (requires confirmation)
"Delete VM TestServer" # Shows warning
"Delete VM TestServer with confirmation" # Executes deletion
# Resource modification (requires confirmation)
"Modify VM WebServer01 to have 8 CPUs and 16GB RAM with confirmation"
# Bulk operations (requires confirmation)
"Delete VMs: OldServer1, OldServer2, OldServer3 with confirmation"
```
## Development
### Build and run locally
```bash
docker build -t vsphere-mcp-server .
docker compose up -d
```
### Dependency pinning
`mcp==1.14.1` requires `pydantic._internal._typing_extra.eval_type_backport`,
which was removed in pydantic 2.14. Keep `pydantic` pinned to `2.13.x` in
`requirements.txt`, otherwise the server fails at import time.
### Container checks
```bash
# Import sanity check (also used by CI)
docker run --rm vsphere-mcp-server:ci python -c "from vsphere_mcp_server import server"
```
This server cannot be deployed
Maintenance
ActivityNo data
ResponsivenessOutdated data