vsphere-console-mcp
Provides tools for interacting with VMware vSphere VM consoles through vCenter, enabling agents to list VMs, capture console screenshots, and send mouse and keyboard input to VMs without installing anything in the guest.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@vsphere-console-mcp web-02 stopped responding; check its console."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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, norequests. 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
Situation | What the agent does |
A VM is unreachable over the network | Reads the console: kernel panic, emergency-mode prompt, full disk, a hung boot; tells you what it sees |
Incident triage | Screenshots several VMs in turn and summarizes which are at a login prompt and which are stuck |
Windows VM stuck before sign-in | Reads update/repair screens, sends |
OS installation, first boot, OOBE | Goes through screens that have no network or automation hook yet |
BIOS / UEFI | Reads firmware screens and changes settings with the keyboard |
Labs, training, homelabs | Drives disposable VMs end to end, including the part before SSH works |
Runbooks and tickets | Captures the exact console screen |
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-mcpOr 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 checkcheck 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-mcpClaude 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
action | What it does |
| Lists the VMs the account can see (and the allow-list permits): power state, guest OS, IP address |
| Returns a PNG of the screen (scaled to |
| Mouse at |
| Types text with scan codes for the guest's |
| Key combinations: |
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.
Variable | Default | Meaning |
| — | vCenter address, e.g. |
| — | The account. Prefer the credentials file to putting the password in client config |
| — | Path to a |
| system CAs | CA bundle for vCenter's certificate (e.g. your VMCA root certificate) |
| off |
|
| all | Comma-separated name patterns ( |
| off |
|
|
| Default guest keyboard layout: |
| off | File to append a JSON line per call to ( |
|
| After vCenter rejects the password, do not try again for this long ( |
|
| Where the login-failure mark is kept |
|
| Seconds per request |
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
Privilege (UI name) | Privilege ID | Needed for |
Read-only (part of every role) |
| Login, listing VMs |
Virtual machine → Interaction → Console interaction |
|
|
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:$trueWith 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-ManagedScope 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=1makes this server refuse input, but the server enforces it, not vCenter.VSPHERE_VM_ALLOWis 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_LOGadds 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,enterand shortcuts are deterministic. After a click,then_lookand 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.
layoutmust 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 useusuntil configured otherwise.Each tool call opens one console connection, sends all its events (a whole
typeordrag), 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, closesThe 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:
usandjis. 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/pytestThe 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.
Available Tools
1 toolvmADestructive
Operate the screen of a VMware vSphere virtual machine through vCenter, the same way its console window does: look takes a picture of the VM's screen, click/move/drag/scroll use its mouse, type/key use its keyboard. Nothing is installed in the VM, so it also works at sign-in and lock screens, BIOS, installers, and when the VM's own network is down. This may be a real machine that people are using: look before acting, and click or type only what the user asked for. Name the VM in every call (vm=...); action='vms' lists them. There is no way to power on/off, reset or reconfigure a VM with this tool. Do not restart, shut down or sign out of a VM from its screen unless the user asked for exactly that.
Actions:
vms: the VMs vCenter knows, with power state, guest OS and IP address.
look: a picture of the VM's screen (at most max_width pixels wide, default 1568), and the real screen size.
click: at rx,ry (0-1000 across and down the screen, as seen in the look picture) or x,y (real screen pixels). button left/right/middle, count=2 for a double-click.
move: put the mouse at rx,ry (hover menus, tooltips).
drag: press at from_rx,from_ry (or from_x,from_y), move, release at rx,ry (or x,y).
scroll: amount notches at rx,ry (positive = up, negative = down).
type: type text with the VM's keyboard; only characters on the keyboard ("\n" presses Enter). layout is the guest's keyboard layout (us or jis); symbols come out wrong with the wrong layout.
key: press keys, e.g. "ctrl+alt+delete", "win+r", "alt+tab", "tab tab enter" (space-separated). then_look=true returns a new picture after click/move/drag/scroll/type/key. Look again before deciding that an action worked.
Inputs: action (required), x, y, rx, +14 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 1 tool
With a single tool, the real disambiguation burden falls on the action enum, and those actions are well-differentiated: look, click, move, drag, scroll, type and key each map to a distinct console input or observation. Minor overlap exists between move and click (a click inherently moves the pointer) and between type and key, but the descriptions make the intended use of each clear.
Action names are uniformly short lowercase words (vms, look, click, move, drag, scroll, type, key), plus a consistent then_look modifier. The lone tool name 'vm' is a bare noun rather than a verb_noun form, and 'vms'/'look' mix noun and verb styles slightly, but with one tool there is no convention clash to speak of.
Everything lives behind one multiplexed 'vm' tool, which is thin for a surface this broad — an agent must read a long action list and cannot discover capabilities from tool names alone. The multiplexing is a defensible way to avoid power-operation confusion, but 1 tool for the whole vSphere console domain sits at the borderline end of the scale.
The console-interaction domain is well covered: VM enumeration with power/IP metadata, screen capture with scaling, full mouse (click/move/drag/scroll), and keyboard (type/key) input, all with then_look feedback. Gaps are minor and explicitly scoped out (no power on/off or reconfiguration), though clipboard/file transfer and waiting-for-screen-change helpers are absent.
Maintenance
Related MCP Connectors
Connect AI assistants to explicitly paired computers, servers, and VMs for permitted remote actions.
Linux VMs for AI agents: create VMs, run commands, edit files and open preview URLs.
Cloud desktops for AI agents: create a Linux computer, see its screen, click, type and run tasks.
- DNS-DATA RemoteDeprecatedcom.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to manage VMware vSphere virtual infrastructure through comprehensive operations including VM power control, snapshot management, resource monitoring, performance analytics, and bulk operations with built-in safety confirmations for destructive actions.-
- FlicenseNot gradedqualityCmaintenanceEnables AI agents to manage VMware vSphere infrastructure through 55 typed tools built on the govc CLI. It supports comprehensive operations including VM lifecycle management, snapshot control, datastore navigation, and networking configuration.5-
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to control and automate Incus/QEMU virtual machines via SSH, supporting mouse/keyboard, screenshots, commands, and lifecycle management.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI clients to control VMware Workstation virtual machines by viewing the console, operating the mouse and keyboard, running guest commands, and managing power and snapshots across multiple named Windows and Linux VMs.1MIT