vcenter-mcp

A Model Context Protocol server that exposes VMware vCenter / ESXi VM lifecycle tools to Claude Code and other MCP clients. Built on pyVmomi.

What it does

• List VMs on a vCenter datacenter (grouped by host) or on a standalone ESXi host
• Create a VM (network-boot first; thin or thick provisioning; nested-virt option for ESXi targets)
• Power VMs on and off
• Delete VMs (powers off first if running, then destroys from disk)

Lookups accept either a display name or a moref ID (e.g. `vm-42`) — the moref path skips the inventory scan and is faster on large environments.

Prerequisites

• Python 3.10 or newer
• A vCenter Server or standalone ESXi host you can reach over the network
• A vSphere account with the privileges needed for whatever you plan to do (read-only is enough for `list_vms`; create / delete need the corresponding VM and resource-pool privileges)

Install

Install into a project-local virtualenv. Using a venv keeps `vcenter-mcp` and its dependencies (notably `pyVmomi`) isolated from your system Python.

From a clone of this repository:

python3 -m venv .venv
.venv/bin/pip install --upgrade pip
.venv/bin/pip install -e .

For development (also installs pytest):

.venv/bin/pip install -e ".[dev]"

> Throughout this README, commands use `.venv/bin/...`. You can instead `source .venv/bin/activate` once per shell and drop the prefix — same result.

Configure a target

Run the interactive setup using the venv's Python:

.venv/bin/python -m vcenter_mcp setup

You'll be prompted for:

1. A target name (e.g. `lab-vcenter`) — used to refer to this target later

2. Host or IP of the vCenter / ESXi

3. Username and password

4. Target type: `vcenter` or `esxi`

5. (vCenter only) Datacenter and cluster names

6. Datastore name

7. One or more network profiles, each a name plus one or more portgroup names

The setup writes a config to `~/.config/vcenter-mcp/config.json` (mode `0600`). Re-run it any time to add another target or update an existing one.

Config file shape

{
  "default_target": "lab-vcenter",
  "targets": {
    "lab-vcenter": {
      "host": "vcenter.lab.example.com",
      "user": "admin@vsphere.local",
      "password": "...",
      "type": "vcenter",
      "datacenter": "Lab DC",
      "cluster": "Lab Cluster",
      "datastore": "datastore1",
      "networks": {
        "standard": ["VM Network"],
        "secure-boot": ["pg-secure-1", "pg-secure-2"]
      },
      "default_network": "standard"
    }
  },
  "templates": {
    "esxi":   { "cpu": 4, "ram_mb": 16384, "disk_gb": 100, "disk_provisioning": "thin", "guest_id": "vmkernel7Guest", "vhv": true },
    "ubuntu": { "cpu": 2, "ram_mb": 4096,  "disk_gb": 40,  "disk_provisioning": "thin", "guest_id": "ubuntu64Guest",  "vhv": false },
    "rhel":   { "cpu": 2, "ram_mb": 4096,  "disk_gb": 40,  "disk_provisioning": "thin", "guest_id": "rhel9_64Guest",  "vhv": false }
  }
}

A network profile is a list of portgroups; the first entry becomes the boot NIC. To add your own VM types, add entries to `templates` — `vm_type` strings passed to `create_vm` are matched against this dict.

Register with Claude Code

Register the MCP server using the venv's Python by absolute path. Claude Code launches the server in a fresh shell that does not inherit your activated venv, so the absolute path is required — pointing at a bare `python` here will fail to import `vcenter_mcp`.

VCENTER_MCP_DIR="$(pwd)"   # run this from the repo root, after install
claude mcp add --scope user vcenter -- "$VCENTER_MCP_DIR/.venv/bin/python" -m vcenter_mcp

Or just inline the absolute path you want:

claude mcp add --scope user vcenter -- /absolute/path/to/vcenter-mcp/.venv/bin/python -m vcenter_mcp

Read tools (`list_vms`) are safe to allow without prompting. Add it to `permissions.allow` in `~/.claude/settings.json`:

{
  "permissions": {
    "allow": [
      "mcp__vcenter__list_vms"
    ]
  }
}

The destructive tools (`create_vm`, `power_on_vm`, `power_off_vm`, `delete_vm`) are intentionally not in the default allow-list — Claude will prompt you per call.

Tools

`list_vms`

List VMs on a target using a single PropertyCollector RPC (no per-VM round trips).

Each VM in the returned list includes:

On error, returns a single dict with an `error` key.

`create_vm`

Create a VM that network-boots first.

`power_on_vm`

Power on a VM by display name or moref ID (e.g. `vm-42`).

`power_off_vm`

Hard power off a VM by display name or moref ID (e.g. `vm-42`).

`delete_vm`

Permanently delete a VM (powers off first if running, then destroys from disk).

Connection management

`vcenter-mcp` maintains a shared `ServiceInstance` per `user@host` combination for the lifetime of the MCP server process rather than opening and closing a new connection on every tool call.

Session lifecycle:

• Created on the first tool call for a given target
• Reused on all subsequent calls with the same credentials
• Reconnected automatically if a liveness ping (`currentSession`) detects the session has expired
• Disconnected explicitly when a session is replaced (ping failure) or invalidated (`NotAuthenticated` / `SecurityError` fault)

Session sharing rules:

Concurrent tool calls are safe — a `threading.Lock` guards all cache reads and writes.

Notes on TLS

`vcenter-mcp` connects with an unverified SSL context, which is the same default that `govc` and most pyVmomi sample code use because lab vCenters very commonly have self-signed certs. If your target uses a properly-signed certificate and you'd prefer real verification, swap `_ssl_context()` in `src/vcenter_mcp/client.py`.

Development

python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest

Tests run on Python 3.10, 3.11, and 3.12 in CI (see `.github/workflows/test.yml`).

License

Apache-2.0