VMware MCP

A Model Context Protocol server for VMware vSphere. It gives an AI assistant read access to your vCenter Server or standalone ESXi host — inventory, performance counters, events and alarms — and, when you explicitly allow it, the ability to power VMs on and off, take snapshots, clone, reconfigure and migrate them.

It talks to vSphere with pyVmomi, the official VMware Python SDK, over the same vSphere Web Services API the vSphere Client uses. No agent, no appliance, and nothing to install on your hosts.

Read-only by default. Out of the box the server refuses every operation that would change your environment. Enabling writes is a deliberate, separate step.

Contents

• Quick start
• Configuring an MCP client
• Permission modes
• Tools
• Resources and prompts
• Configuration reference
• Referring to objects
• Security notes
• Development

Quick start

Requires Python 3.10 or newer and network access to port 443 on vCenter or ESXi.

git clone https://github.com/ISH2YU/VMware-MCP.git
cd VMware-MCP
pip install -e .

Set the connection details and check that they work before wiring anything up to an AI client:

export VMWARE_HOST=vcenter.example.com
export VMWARE_USERNAME='svc-mcp@vsphere.local'
export VMWARE_PASSWORD='...'

vmware-mcp --check

--check logs in, prints the vCenter version, the account it authenticated as and the number of inventory objects it can see, then exits:

{
  "endpoint": "vcenter.example.com:443",
  "permission_mode": "read-only",
  "verify_ssl": true,
  "authenticated_as": "svc-mcp@vsphere.local",
  "server": {
    "name": "VMware vCenter Server 8.0.3 build-24022515",
    "product": "VMware vCenter Server",
    "version": "8.0.3",
    "build": "24022515",
    "api_version": "8.0.3.0",
    "api_type": "VirtualCenter",
    "os_type": "linux-x64",
    "vendor": "VMware, Inc.",
    "instance_uuid": "aaaa-bbbb-cccc",
    "license_product": "VMware VirtualCenter Server"
  },
  "inventory_objects_indexed": 214
}

If the TLS handshake fails, either point VMWARE_CA_BUNDLE at your vCenter's CA certificate or, for a lab, set VMWARE_VERIFY_SSL=false.

Then run the server. It speaks stdio by default, which is what desktop MCP clients expect:

vmware-mcp

Configuring an MCP client

Cursor

Add to ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "vmware": {
      "command": "vmware-mcp",
      "env": {
        "VMWARE_HOST": "vcenter.example.com",
        "VMWARE_USERNAME": "svc-mcp@vsphere.local",
        "VMWARE_PASSWORD": "...",
        "VMWARE_PERMISSION_MODE": "read-only"
      }
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "vmware": {
      "command": "vmware-mcp",
      "env": {
        "VMWARE_HOST": "vcenter.example.com",
        "VMWARE_USERNAME": "svc-mcp@vsphere.local",
        "VMWARE_PASSWORD": "..."
      }
    }
  }
}

Over HTTP

To run the server once and share it, use the streamable HTTP transport:

vmware-mcp --transport streamable-http --host 127.0.0.1 --port 8000

The endpoint has no authentication of its own, so bind it to localhost or put it behind a proxy that does.

Permission modes

VMWARE_PERMISSION_MODE decides how much damage the server can do. Modes are cumulative.

Mode	What it allows
read-only (default)	Inventory, monitoring, events, alarms and performance counters. Every mutating tool refuses with an explanation.
write	Adds power operations, snapshot creation, clone, reconfigure and migrate.
destructive	Adds deleting VMs and reverting or deleting snapshots.

The mode is enforced server-side, before any call reaches vCenter, and it is stated in the server instructions so the model knows what it can attempt. Deleting a VM additionally requires an explicit confirm=true argument and refuses while the VM is powered on.

Belt and braces: give the service account only the vCenter privileges it needs. The permission mode protects against a confused model, not against a compromised one — vCenter roles are the real boundary.

Tools

All 27 tools are prefixed vsphere_.

Inventory

Tool	Purpose
vsphere_about	Product, version, API type, authenticated user and the active permission mode.
vsphere_list_datacenters	Every datacenter.
vsphere_list_clusters	Clusters with capacity, DRS and HA configuration.
vsphere_list_hosts	ESXi hosts with hardware, version and live CPU/memory utilisation.
vsphere_get_host	One host in full, including its VMs, datastores and networks.
vsphere_list_resource_pools	Reservations, limits and current usage.
vsphere_search_inventory	Search by name across object types when you don't know what a name refers to.

Virtual machines

Tool	Purpose
vsphere_list_vms	VMs filtered by name, power state, datacenter, cluster, host, guest OS or IP.
vsphere_get_vm	One VM in full: hardware, disks, NICs, guest networking and filesystems, snapshots.
vsphere_get_vm_summary_by_host	VM counts and vCPU/memory overcommitment per host.

Storage and networking

Tool	Purpose
vsphere_list_datastores	Capacity, free space, provisioned space and over-provisioning.
vsphere_list_networks	Standard port groups, distributed port groups (with VLAN and switch) and opaque networks.

Monitoring

Tool	Purpose
vsphere_list_tasks	Recent tasks, optionally scoped to an object.
vsphere_get_task	Poll a single task by id.
vsphere_list_running_tasks	What vCenter is doing right now.
vsphere_list_events	The audit trail: logins, changes, HA actions, hardware problems.
vsphere_list_alarms	Every currently triggered alarm, red first.
vsphere_get_performance	CPU, memory, disk and network counters for a VM or host, summarised.

Power, snapshots and lifecycle

Tool	Mode	Purpose
vsphere_change_vm_power_state	write	Power on/off, suspend, reset, or ask the guest to shut down or reboot.
vsphere_list_snapshots	read	Snapshot tree plus a flat list with paths.
vsphere_create_snapshot	write	Take a snapshot, optionally with memory or quiesced.
vsphere_revert_to_snapshot	destructive	Revert, discarding later changes.
vsphere_delete_snapshot	destructive	Delete one snapshot, a subtree, or all of them.
vsphere_clone_vm	write	Clone a VM or deploy from a template.
vsphere_reconfigure_vm	write	Change vCPU count, cores per socket, memory or notes.
vsphere_migrate_vm	write	vMotion, storage vMotion, or both.
vsphere_delete_vm	destructive	Delete a VM and its disks. Needs confirm=true.

Long operations (clone, migrate, snapshot) accept wait=false and return a task_id you can poll with vsphere_get_task. When waiting, progress is streamed to the client as MCP progress notifications.

Resources and prompts

Two resources:

• vsphere://inventory/summary — counts and totals for the whole environment, useful as ambient context.
• vsphere://vm/{identifier} — full detail for one VM, by name, moid, UUID or path.

Two prompts:

• troubleshoot_vm(vm) — a diagnostic walkthrough for a slow, stuck or unreachable VM: performance counters for the VM and its host, recent events and tasks, alarms, snapshot age and datastore pressure.
• capacity_report(scope) — cluster and host utilisation, overcommitment ratios, datastores nearing full, and a prioritised list of recommendations.

Configuration reference

Every setting is an environment variable; the flags shown override them.

Variable	Default	Description
VMWARE_HOST	required	vCenter Server or ESXi hostname or IP. Also VSPHERE_HOST.
VMWARE_USERNAME	required	vSphere account. Also VMWARE_USER, VSPHERE_USER.
VMWARE_PASSWORD	required	Password. Also VSPHERE_PASSWORD.
VMWARE_PORT	443	API port.
VMWARE_VERIFY_SSL	true	Verify the TLS certificate.
VMWARE_INSECURE	false	Shorthand for disabling verification.
VMWARE_CA_BUNDLE	—	CA certificate bundle to trust instead of the system store.
VMWARE_PERMISSION_MODE	read-only	read-only, write or destructive.
VMWARE_CONNECT_TIMEOUT	30	HTTP connection timeout in seconds.
VMWARE_TASK_TIMEOUT	600	How long to wait for a vSphere task before handing back its id.
VMWARE_MAX_RESULTS	500	Hard cap on items returned by any listing.
VMWARE_DEFAULT_PAGE_SIZE	100	Page size when a tool call omits limit.
VMWARE_CACHE_TTL	60	Seconds to cache the inventory tree used for path resolution.
VMWARE_MAX_CONCURRENCY	8	Maximum simultaneous calls to vCenter.
VMWARE_LOG_LEVEL	INFO	Log level. Logs go to stderr.
VMWARE_TRANSPORT	stdio	stdio, streamable-http or sse.

Command line flags: --vsphere-host, --vsphere-port, --username, --insecure, --ca-bundle, --permission-mode, --transport, --host, --port, --log-level, --check. Run vmware-mcp --help for details. There is deliberately no --password flag; passwords on a command line end up in the process list and shell history.

Referring to objects

Every tool that takes a VM, host, datastore, network or cluster accepts any of:

• the object name — web-01, matched case-insensitively
• a glob, where a name filter is accepted — web-*, db-0?
• the managed object id — vm-1024, host-42
• a UUID, for VMs and hosts — BIOS or instance UUID
• the inventory path — /Prod/vm/Tier1/web-01, or any suffix of it

When several objects match, the tool lists the candidates with their managed object ids rather than picking one. Listings are paginated and report truncated, so a model can tell the difference between "that's all of them" and "there are more".

Security notes

• Create a dedicated service account in vSphere rather than reusing an administrator. Grant it a read-only role for the default mode; add only the specific privileges you need if you enable writes.
• The password is never returned by any tool. vsphere_about reports the connection settings with the password omitted.
• Certificate verification is on by default. Disabling it is logged as a warning at startup.
• Anything an MCP client can call, a model can call. Permission modes and the confirm flag on deletion exist because prompt injection through, for example, a VM annotation is a real risk. Keep the server in read-only unless a task genuinely needs more.
• Secrets in client config files are stored in plain text by most MCP clients. Prefer a secret manager or environment variables where your client supports them.

Development

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

pytest                     # 200+ tests, no vCenter required
ruff check src tests       # lint
ruff format src tests      # format
mypy                       # type check

The test suite runs against an in-memory vCenter double (tests/fake_vsphere.py) that implements the two seams the server actually depends on: pyVmomi's SOAP stub and the PropertyCollector. Everything above those seams — the real client, the real property specs, the real mappers and the real tools — runs unmodified, so tests exercise the same code paths that talk to a live vCenter.

How it is put together

src/vmware_mcp/
├── config.py          Environment parsing and permission modes
├── errors.py          Error types, all with client-safe messages
├── server.py          MCPServer assembly, resources and prompts
├── cli.py             Argument parsing, --check, transports
├── vsphere/
│   ├── session.py     Connection, TLS, reconnect on session expiry
│   ├── client.py      Async facade; runs pyVmomi on a bounded thread pool
│   ├── query.py       PropertyCollector batching and inventory paths
│   ├── mappers.py     Pure vSphere-to-JSON translation
│   ├── lookup.py      Name/moid/UUID/path resolution
│   ├── tasks.py       Task polling with progress reporting
│   ├── perf.py        Performance counter queries
│   └── monitoring.py  Events, tasks and alarms
└── tools/             One module per area of vSphere

Two decisions worth knowing about:

Everything reads through the PropertyCollector. Touching managed object attributes one at a time costs a round trip each, which is unusable against a vCenter with thousands of VMs. A listing here is a single RetrievePropertiesEx call regardless of how many objects come back.

pyVmomi is synchronous, MCP is not. Blocking calls run on a thread pool bounded by VMWARE_MAX_CONCURRENCY, and vSphere tasks are polled from the event loop rather than blocking a thread, so progress can be streamed and a cancelled request does not strand a worker.

License

MIT. See LICENSE.