# vsphere-mcp-extended

An add-on that extends [`vsphere-mcp-server`](https://github.com/rorymcmahon/vsphere-mcp-server) (an MCP server for VMware vCenter) with a much larger tool surface, built on top of it **without modifying the installed package**.

`vsphere-mcp-server` talks to vCenter's REST API, which is read-only inventory plus basic power operations and doesn't expose live performance counters. This add-on imports the base package's `FastMCP` instance and registers additional tools on it using [pyVmomi](https://github.com/vmware/pyvmomi) (vCenter's SOAP API), which unlocks real-time and historical performance data plus a large set of write operations.

## What it adds

**Performance & monitoring**
- `get_vm_performance` — live CPU/memory/ballooning/swap stats for one VM
- `get_vm_disk_performance` — live per-disk IOPS, latency, throughput
- `list_vm_performance` — bulk snapshot across *all* VMs in a single API round trip, sorted by CPU usage, flags VMs under memory pressure
- `get_vm_performance_history` — historical min/avg/p95/max over N days (CPU%, CPU ready%, memory%, swap, disk latency, network) using vCenter's rolled-up historical intervals — the right tool for "is this VM actually bottlenecked, and on what"

**VM lifecycle**
- `create_vm` — create a new VM (datastore, cluster, network, disk, guest OS type)
- `reconfigure_vm_resources` — change vCPU / RAM on an existing VM
- `add_vm_disk`, `get_vm_disks`, `resize_vm_disk` — disk management
- `get_vm_network` — reliably resolve the actual portgroup a VM's NIC is on (the base package's REST tool often reports "Unknown")

**Snapshots**
- `list_vm_snapshots`, `list_all_vm_snapshots` (bulk scan across all VMs)
- `create_vm_snapshot`, `remove_vm_snapshot`, `revert_vm_snapshot`

**Content Library / ISOs**
- `find_content_library_item`, `get_content_library_item_files`
- `browse_datastore` — read-only datastore browsing, useful for resolving real on-disk paths before mounting
- `mount_iso` — attach a Content Library ISO to a VM's CD-ROM

**Hosts, clusters & networking**
- `list_cluster_hosts`
- `add_portgroup_to_host`, `add_portgroup_to_cluster` — create standard-vSwitch portgroups (per-host is more robust for large clusters; the cluster-wide version isolates failures per host instead of aborting the batch)
- `migrate_vm_host` — relocate/vMotion a VM to a different host
- `diagnose_vm_datastore_access` — check whether a VM's current host can actually see a given datastore (useful when device reconfigures fail with "backing file is not accessible from host")

All tools are read-only except: `create_vm`, `reconfigure_vm_resources`, `add_vm_disk`, `resize_vm_disk`, `mount_iso`, `create_vm_snapshot`, `remove_vm_snapshot`, `revert_vm_snapshot`, `migrate_vm_host`, `add_portgroup_to_host`, `add_portgroup_to_cluster`.

## Install

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

Credentials are handled entirely by `vsphere-mcp-server`'s own credential store (macOS Keychain on macOS, with a GUI prompt on first use / expiry). This add-on does not read or store credentials itself — it calls the base package's `get_credentials(hostname)`.

## Run

Run this file instead of `python -m vsphere_mcp_server.server`:

```bash
python vsphere_perf_addon.py
```

It registers every tool from the base package plus everything listed above on the same server instance.

## Use with Claude Desktop

Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "vsphere": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/vsphere_perf_addon.py"]
    }
  }
}
```

Restart Claude Desktop afterwards.

## Notes / gotchas

- **Credential expiry**: the base package's macOS Keychain cache has a TTL (commonly ~4 hours). When it expires, a native GUI password prompt appears that only a human can fill in — any in-flight tool call will hang until it's filled or times out. If you see a timeout or "authentication failed" from a client automating this server, have a human fill in the OS prompt, then retry.
- **Historical performance granularity**: `get_vm_performance_history` depends on which historical intervals are enabled/retained on your vCenter (Configure → General → Statistics). Disk latency at longer rollups (weekly/monthly) is often not collected unless the statistics level is raised — CPU/memory/network usually are.
- **Bulk operations**: `list_vm_performance` and `list_all_vm_snapshots` use a single `PropertyCollector.RetrieveContents` call regardless of VM count, so they stay fast with hundreds of VMs. Prefer these over looping `get_vm_performance` per VM.
- **`create_vm` / `add_portgroup_to_cluster` on large batches**: creating multiple VMs in parallel can occasionally hit a transient `vim.fault.CannotAccessFile`; retrying the single failed call usually succeeds. For portgroup rollout across many hosts, `add_portgroup_to_host` (single host) isolates failures better than the cluster-wide call, which can time out on a large cluster.

## Requirements

- Python 3.9+
- A vCenter service account with at least: VM read/write privileges for the mutating tools you plan to use, Content Library → Read, and read access to hosts/datastores/networks.
- `vsphere-mcp-server` and `pyvmomi` (see `requirements.txt`)

## License

MIT — see `LICENSE`.