vsphere-console-mcp

Let an AI agent see and use the console of your VMware vSphere VMs — screen, mouse and keyboard — through vCenter, with nothing installed in the guest.

日本語

An MCP server with one tool, vm, that works the way the vSphere Client's console window does. Because it never touches the guest OS, it reaches the places SSH, RDP and in-guest agents cannot: sign-in and lock screens, the BIOS/UEFI setup, OS installers, a VM whose network is down, a Windows VM stuck on a blue screen or "Preparing to configure Windows".

You:   web-02 stopped answering. Look at its console.
Agent: [vm look web-02] It is in emergency mode: "Give root password for maintenance".
       The journal line above says /data failed to mount. Do you want me to log in and check /etc/fstab?

It is meant for an agent working with a person, not for unattended automation: the person decides, the agent looks, reads and types. See Good to know before you use it.

Why this one

• Zero dependencies. Python standard library only — no pyVmomi, no websockets, no requests. It speaks vSphere SOAP, the console screenshot endpoint and WebMKS (RFB over a websocket) itself, in about 1,300 lines you can read in an afternoon. Installing it pulls in exactly one package.

• Least privilege, verified. The service account needs Read-only plus one privilege, Console interaction. Typing works through the console connection, so it does not need VirtualMachine.Interact.PutUsbScanCodes (or any power, snapshot or configuration privilege).

• No power button. There is no code to power on/off, reset, snapshot or reconfigure a VM.

• Correct symbols on non-US keyboards. Keys go as scan codes for the guest's layout (us, jis), not as keysyms that vCenter would remap as US, so @ : _ \ arrive as typed.

• Guardrails on the MCP side too: an allow-list of VM names, a read-only mode, a JSON audit log that never records typed text, and a guard that stops retrying a rejected password before vCenter locks the account.

Related MCP server: VMWare MCP

Use cases

Quick start

1. Install

pipx install git+https://github.com/Razer0028/vsphere-console-mcp
# or: uv tool install git+https://github.com/Razer0028/vsphere-console-mcp
#     pip install git+https://github.com/Razer0028/vsphere-console-mcp

Or run it without installing: uvx --from git+https://github.com/Razer0028/vsphere-console-mcp vsphere-console-mcp.

2. Give it an account

Create a dedicated vCenter account with the role in Permissions, and put its details in a file only you can read:

install -m 600 /dev/null ~/.config/vsphere-console-mcp.env
cat >> ~/.config/vsphere-console-mcp.env <<'EOF'
VSPHERE_SERVER=https://vcenter.example.com
VSPHERE_USER=svc-ai-console@vsphere.local
VSPHERE_PASSWORD=...
EOF
VSPHERE_CREDENTIALS_FILE=~/.config/vsphere-console-mcp.env vsphere-console-mcp check

check logs in and prints how many VMs the account can use. vsphere-console-mcp vms and vsphere-console-mcp look <vm> -o screen.png work from the shell too.

3. Add it to your MCP client

Claude Code

claude mcp add vsphere-console -e VSPHERE_CREDENTIALS_FILE=$HOME/.config/vsphere-console-mcp.env -- vsphere-console-mcp

Claude Desktop, Cursor, VS Code and other clients (mcpServers JSON):

{
  "mcpServers": {
    "vsphere-console": {
      "command": "vsphere-console-mcp",
      "env": { "VSPHERE_CREDENTIALS_FILE": "/home/me/.config/vsphere-console-mcp.env" }
    }
  }
}

If only another machine can reach vCenter, run the server there over SSH: "command": "ssh", "args": ["jump-host", "vsphere-console-mcp"].

Docker: build the image from this repository (docker build -t vsphere-console-mcp .), then docker run -i --rm -e VSPHERE_CREDENTIALS_FILE=/run/creds.env -v ~/.config/vsphere-console-mcp.env:/run/creds.env:ro -v vsphere-console-mcp-lock:/lock vsphere-console-mcp. Keep VSPHERE_LOCK_DIR on a volume that every container using the account shares; see Accounts and lockout.

The vm tool

vm names a VM by its vCenter name, its managed object id (vm-123) or its IP address, and is required on every call except vms — there is no default VM, so an agent cannot act on a machine nobody named. then_look: true returns a fresh screenshot after an input action.

Configuration

All settings are environment variables. VSPHERE_CREDENTIALS_FILE may hold any of them as KEY=VALUE lines; variables set in the environment win.

vCenter's certificate is verified unless VSPHERE_INSECURE=1. The certificate of each ESXi host (used for keyboard and mouse input) is always checked against the SHA-1 or SHA-256 thumbprint that vCenter puts in the WebMKS ticket, independently of VSPHERE_INSECURE.

Permissions (for vCenter administrators)

Create a dedicated service account for the agent; do not reuse a person's account or an administrator's.

The role

That is all. Tested with vCenter 8.0.3: a Read-only account lists VMs but gets HTTP 401 for the screen and NoPermission (VirtualMachine.Interact.ConsoleInteract) for input; with Console interaction added, everything works, without VirtualMachine.Interact.PutUsbScanCodes.

With PowerCLI:

New-VIRole -Name "AI Console Operator" -Privilege (Get-VIPrivilege -Id System.Anonymous,System.View,System.Read,VirtualMachine.Interact.ConsoleInteract)
New-VIPermission -Entity (Get-Folder "AI-Managed") -Principal "VSPHERE.LOCAL\svc-ai-console" -Role "AI Console Operator" -Propagate:$true

With govc:

govc role.create "AI Console Operator" System.Anonymous System.View System.Read VirtualMachine.Interact.ConsoleInteract
govc permissions.set -principal svc-ai-console@vsphere.local -role "AI Console Operator" -propagate=true /Datacenter/vm/AI-Managed

Scope it

• Grant the role on a VM folder (or a resource pool), not on the vCenter root. The account then sees only the VMs there; nothing else exists for it. This is the main control, and vCenter enforces it.

• vSphere has no privilege that allows the screen but not input — Console interaction covers both. VSPHERE_READ_ONLY=1 makes this server refuse input, but the server enforces it, not vCenter.

• VSPHERE_VM_ALLOW is a second, client-side filter (for example to keep production VMs out of reach even inside a shared folder). Treat it as defense in depth, not as the boundary.

• If your organization manages permissions through SSO or AD groups, grant the role to a group and put the service account in it.

• vCenter records the account's logins and console tickets in its events. VSPHERE_AUDIT_LOG adds what the agent looked at and did on the screen.

Accounts and lockout

vCenter Single Sign-On locks an account after a few failed logins (5 by default). When vCenter rejects the password (InvalidLogin), this server writes a mark and does not try that account again for VSPHERE_LOCKOUT_MINUTES (15) — in this process and in every process that shares VSPHERE_LOCK_DIR — so a wrong password in a config file does not lock the service account for everyone. Network errors, timeouts and an overloaded vCenter do not set the mark. In containers, put VSPHERE_LOCK_DIR on a shared volume, or each new container starts without the mark. The server keeps one session for its lifetime and logs out on exit (including SIGTERM).

Good to know before you use it

• Typing into a VM is full control of that VM. No power privilege does not mean safe: if a shell is open, the agent can type anything a person could. Keep a human approving input actions (most MCP clients ask before each tool call; do not auto-approve this tool for production VMs), and scope the account to the VMs it may touch.

• Prefer the keyboard to the mouse. Vision models estimate positions in a screenshot only roughly; a click can land a few pixels off. tab, arrow keys, enter and shortcuts are deterministic. After a click, then_look and check.

• Screens move faster than an agent. Look → think → act takes seconds, so a boot menu with a 3-second timeout or a progress bar will not wait. This is a tool for screens that wait for input.

• layout must match the guest's current keyboard layout. Keys are sent as scan codes and the guest maps them. BIOS screens, installers and Linux text consoles usually use us until configured otherwise.

• Each tool call opens one console connection, sends all its events (a whole type or drag), and closes it. If the connection breaks in the middle, the server releases any keys it was holding; if it cannot, the result says so, so you can look and press the key once.

• Screenshots are sent to your AI provider as part of the conversation. Do not point the agent at consoles that show data you may not send there.

• Passwords are used only in the login request and are never put in tool results, errors, the audit log or command lines; neither are WebMKS tickets. The audit log records the length of typed text, not the text, and records single-character keys as *.

How it works

MCP client ──stdio──▶ vsphere-console-mcp
                        ├─ SOAP  https://vcenter/sdk           Login, CreateContainerView + RetrievePropertiesEx (list),
                        │                                      AcquireTicket("webmks")
                        ├─ HTTPS https://vcenter/screen?id=vm   the console screenshot (PNG, scaled by vCenter)
                        └─ WSS   wss://esxi/ticket/<ticket>     RFB over a websocket: pointer events and VMware's
                                                                key-scancode message; connects, sends, closes

• The RFB connection asks for a shared session, so it does not disconnect anyone else's console window. It never asks for screen updates and never changes the guest's resolution.

• The screen size can change under you (another console window may resize it). Relative coordinates always point at the same place; pixel coordinates are mapped from the size seen at the last look.

Limitations

• Keyboard layouts: us and jis. Other layouts are welcome as pull requests (keyboard.py).

• Text that is not on the keyboard (e.g. CJK, emoji) has to be entered with the guest's input method.

• Tested with vCenter 8.0.3 and Debian and Windows 11 guests. A standalone ESXi host without vCenter is untested.

• The WebMKS wire protocol (RFB over a websocket, plus VMware's own key-scancode message) is not publicly documented; VMware only published a JavaScript SDK on top of it. The SOAP calls have been stable for many vSphere releases, but a future version could change the console protocol; please open an issue with the version if it stops working.

Related projects

This server only does the console. For inventory, power and configuration, use it alongside a vSphere management MCP server such as InfraMCP/vsphere-mcp-server (VMs, hosts, datastores, networks, power on/off) or VMware's own tooling — giving each its own account and role.

Development

python -m venv .venv && .venv/bin/pip install -e '.[test]' && .venv/bin/pytest

The tests use no network: SOAP and WebMKS are faked.

License

MIT. See LICENSE. VMware, vSphere, vCenter and ESXi are trademarks of Broadcom; this project is not affiliated with or endorsed by Broadcom. Security issues: SECURITY.md.