hyperv-console-mcp
Summary: A local, policy-gated Hyper-V MCP server for host/VM management, guest diagnostics and automation, console control, media/serial/debug setup, and lab evidence workflows.
Inspect Hyper-V host health and list/get/wait for VMs, including state, devices, memory, network, and checkpoint counts.
Control VM power: start, shutdown, save, pause, resume, forced turn off, and reset with confirmation.
List, create, restore, and delete checkpoints, with exact confirmation for restore/delete.
Run guest diagnostics over PowerShell Direct: OS/status, processes, services, event logs, and arbitrary PowerShell execution.
Read/write guest files as base64 with size limits, SHA-256, overwrite protections, and confirmation.
Use lab tools to initialize diagnostics, stage hash-verified packages, verify package integrity, and collect logs/evidence/dumps without executing staged content.
Read local operation lifecycle events.
Send synthetic console input: text, key chords, key down/up, mouse movement/clicks/buttons/scroll, ordered batches, and Ctrl+Alt+Delete.
Read console display info and capture screenshots from an existing VMConnect window.
Manage DVD media: list drives, mount ISOs while the VM is off, optionally boot-first, and eject.
Use COM1 serial console: status, attach a reader with local log, read retained output, send text, and disconnect.
Prepare serial kernel debugging host-side and guest BCD settings, and read debug availability/config.
All mutations are gated by allowlists/capability flags and confirmation parameters; audit/event output avoids secrets, commands, and typed text.
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., "@hyperv-console-mcp list my Hyper-V VMs and show the status of NORTH-Test"
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.
hyperv-console-mcp
A local, policy-gated Model Context Protocol server for Hyper-V on Windows. It combines VM management, checkpoints, PowerShell Direct diagnostics, synthetic keyboard/mouse input, console screenshots without VMConnect, installation media, serial consoles, and serial WinDbg preparation and a live kd.exe kernel-debugging session in one stdio server.
Alpha status: 1202 unit/transport tests and a real MCP stdio client smoke test pass locally, including a local Windows named-pipe transport test and one assertion set that runs over both guest transports; the smoke checks each profile's tool surface, per toolset, over a real stdio client. Live validation on NORTH-Test covered the lab cycle, autologon, kd over COM1, SSH end to end, package staging and host-side verification over both guest transports (including a tampered file being named in the refusal), a ~100 KB guest_exec and a 100 KB file transfer over both guest transports, and the test-signing/debug BCD round trip on a pt-BR guest; docs/PROJECT.md records what was and was not exercised. The package builds as an sdist and wheel. No driver, mapper, or guest payload is bundled by this project; in the lab profile lab_run executes only a package the operator staged.
Highlights
69 MCP tools in twelve toolsets, with read-only/destructive annotations and structured results; a profile registers only its own toolsets, so the default surface is 31 tools rather than every schema in every conversation.
Inventory, pause/resume, bounded state waiting, power, checkpoints, and bounded guest file transfer.
A running VM reports its guest's computer name and OS from the Hyper-V key-value pair exchange, so a VM can be identified before any guest credential exists.
Guest OS health, processes, services, and recent event logs through PowerShell Direct.
Hyper-V
Msvm_KeyboardandMsvm_SyntheticMouse, explicit key/button states, and ordered console batches: works without guest networking.Persistent local PowerShell worker, avoiding process/module startup on every request.
COM1/named-pipe WinDbg preparation with separate host and guest phases, and no automatic shutdown or reboot.
Dedicated serial reader with bounded retained output and a persistent local log.
Existing DVD-drive ISO mount/eject and optional boot-first selection while the VM is Off.
Exact confirmation gates for forced power, restore/delete, debug preparation, media changes, and overwrite.
No guest password in tool arguments, command lines, or audit records.
A native dashboard and a non-executing, hash-verified driver-lab transfer workflow.
A replaceable backend and tests that never mutate live VMs.
Related MCP server: Hyper-V Sandbox MCP Server
Requirements
Windows 10/11 Pro/Enterprise or Windows Server with the Hyper-V management platform.
Windows PowerShell 5.1 and the Hyper-V PowerShell module.
Python 3.11+ with
mcp>=2.3,<3and Pillow.Hyper-V management permission (elevated host or suitably authorized account).
Windows guest with PowerShell Direct for guest command/file tools.
Console screenshots come from the Hyper-V console thumbnail, so no VMConnect window or interactive session is needed; only
console_screenshot(source="vmconnect")uses one. Console input has no network dependency.
Install
Never used PowerShell? docs/QUICKSTART.md is the install in plain language, with the three questions the window asks on its first run.
Three ways in, in the order to consider them:
The installer.
HyperVConsoleMCP-Setup-<version>.exefrom the releases page: one download, no administrator prompt during installation, and no Python — the runtime is inside it. It installs into%LOCALAPPDATA%\Programs\Hyper-V Console, then runshyperv-setuponce, so the client config, the shortcut and the self-test happen during the install. The window itself always runs elevated; Windows asks once when it opens.winget.
winget install maiconzeraxd.HyperVConsoleMCP, once the manifest has been accepted intomicrosoft/winget-pkgs.packaging/winget/holds the manifests this project submits andpackaging/winget/README.mdsays what changes per release.From source, below: what development and the lab use, and the only path that needs Python.
scripts/install.ps1 runs the same routine for a machine where the package is already
installed. It is the advanced path and not the first one: downloading and running a script as
administrator is a habit worth not forming for a tool that runs as a service and controls
Hyper-V.
From the repository root, using a virtual environment is recommended:
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e '.[dev]'
.\.venv\Scripts\python.exe -m pip install -e '.[ui]' # the WebView2 window; tkinter works without it
.\.venv\Scripts\python.exe -m pytestSet the protected environment before launching the MCP host. The shortest path is one access level per VM, written by you — never by a tool — into %LOCALAPPDATA%\HyperVConsoleMCP\access.json:
hyperv-access set "NORTH-Test" lab # read-only | control | lab
hyperv-access list # what each VM may do, and the file in useA level is also the allowlist: a VM with no level is not reachable. read-only lists and reads the VM and changes nothing; control adds power, checkpoints, console input, screenshots and media; lab adds guest access and the debugger. The same choice is on the dashboard's Overview page, and both writers tell a running service to re-read the file, so a level takes effect without a restart. The equivalent environment variables still work and are what a test or a one-off run should use:
$env:HYPERV_MCP_ALLOWED_VMS = 'NORTH-Test'
$env:HYPERV_MCP_ALLOW_POWER = 'false'
$env:HYPERV_MCP_ALLOW_CHECKPOINTS = 'false'
$env:HYPERV_MCP_ALLOW_GUEST = 'false'
$env:HYPERV_MCP_ALLOW_CONSOLE = 'false'
$env:HYPERV_MCP_ALLOW_SCREENSHOTS = 'false'
$env:HYPERV_MCP_ALLOW_DEBUGGER = 'false'
$env:HYPERV_MCP_ALLOW_MEDIA = 'false'
hyperv-console-mcpA VM with a level takes its capabilities from that level — per VM is more specific than a host-wide flag — and a VM without one keeps the older behaviour, where the profile and the HYPERV_MCP_ALLOW_* variables decide for every VM at once. HYPERV_MCP_ALLOWED_VMS narrows the file rather than replacing it.
See client configuration for a stdio JSON example. All mutations require an explicit VM allowlist and their own capability flag. A .env file is not loaded automatically.
hyperv-install writes that entry for you, into the client's own file, and copies the file first:
hyperv-install --client claude # also: codex, cursor; repeat --client for more
hyperv-install --client claude --uvx # `uvx hyperv-console-mcp` instead of this interpreter
hyperv-install --client claude --profile lab --shortcut # plus a Start Menu shortcut to the windowIt merges one mcpServers.hyperv entry and leaves every other server and setting untouched, appends one [mcp_servers.hyperv] section to Codex's TOML rather than re-serialising it, and refuses — without writing — a file it cannot parse. Running it twice reports unchanged instead of rewriting.
The whole install is one routine, and it starts by asking the machine whether it can run this at all:
hyperv-setup --check # edition, Hyper-V state; changes nothing, exit 0 means go
hyperv-setup # every detected client's config, the shortcut, the self-test
hyperv-setup --uninstall # takes the entry back out; keeps your credentials and data unless asked--check refuses Windows Home in one sentence instead of failing inside a feature install, and stops with the exact Enable-WindowsOptionalFeature line when Hyper-V is installed but switched off. scripts/install.ps1 is the same routine for a machine where the package is already present, with -Check and -Uninstall; it is documented as the advanced path, not the first one.
HYPERV_MCP_PROFILE picks the default toolset list (safe or lab); HYPERV_MCP_TOOLSETS overrides it with a comma-separated list such as core,console,guest or all. An unknown name is refused at startup rather than silently ignored.
Zero configuration
Nothing about a particular VM is built into the program, and the environment above is the narrowing, not the setup:
The VMs come from Hyper-V.
vm_listreads them; a running VM also reports its guest's computer name and OS from the key-value pair exchange, so it can be identified before any guest credential exists. The window opens the only VM Hyper-V reports and asks from a list when there are more than one — no name is compiled in.Host capabilities are detected, not configured.
host_statusreports whether the hypervisor is present and whethervmms/vmcomputeare running;debug_statussays whetherkd.exewas found and where; the window falls back to tkinter when the WebView2 runtime is absent, instead of refusing to open.The directories create themselves under
%LOCALAPPDATA%\HyperVConsoleMCP\— events, transfers, ssh, kd, lab packages and evidence — the first time something needs them.One level per VM replaces the flags.
hyperv-access set <vm> labis the whole configuration for a VM, and it is re-read when it changes rather than frozen at startup.
A missing capability comes back as a refusal that carries the call which would fix it, so a client can either ask you or, in the lab profile, do it.
Tool groups
Every tool belongs to one toolset. A profile decides which toolsets are registered, and a
tool that is not registered is never advertised, so its schema never enters the model's
context. The safe profile registers 31 tools, lab registers 47, HYPERV_MCP_TOOLSETS
replaces the set outright, and all enables everything (69 tools).
Toolset | Tools | safe | lab |
|
| ✓ | ✓ |
|
| ✓ | ✓ |
|
| ✓ | ✓ |
|
| ✓ | ✓ |
|
| ✓ | |
|
| ✓ | |
|
| ✓ | |
|
| ||
|
| ||
|
| ✓ | |
|
| ✓ | |
|
| ✓ |
Families that only differ by an action share one tool with a typed discriminator, so the
schema carries the choice instead of a dozen near-duplicates: console_input takes an
ordered list of text, keys, key_state, mouse_buttons, move, click, scroll,
wait and ctrl_alt_delete actions; checkpoint takes create/restore/delete;
guest_report takes status/processes/services/events/transport; guest_credential takes
rotate/forget; lab_receipts takes list/get/compare/export; kd_execution takes
break/go; kd_breakpoint takes
set/clear/on_load; kd_inspect takes stack/modules/symbols/analyze/dump
(symbols takes the module it is about, the same question the window's per-driver badge
asks); and
debug_setup crosses transport (serial/kdnet) with action (prepare/guest/
deprovision). vm_get(wait_for=[...]) absorbs the old vm_wait. Read-only tools stay
separate from mutating ones, so a listing never asks for approval.
Power actions are start, shutdown, save, pause, resume, turn_off, and reset. Forced power needs confirm_vm equal to vm_name. Restore/delete need the VM name and exact checkpoint GUID confirmed. Overwriting an existing guest file needs overwrite=true and an exact confirm_path.
guest_read_file/guest_write_file move small content inline (≤ 8 MiB of base64 in one request). guest_put_file/guest_get_file copy whole files between the guest and a host path under one of the configured roots (HYPERV_MCP_TRANSFER_ROOT, HYPERV_MCP_LAB_ROOT, HYPERV_MCP_EVIDENCE_ROOT, HYPERV_MCP_ISO_ROOT), verifying SHA-256 on both sides; they are the right choice for drivers, dumps and anything else measured in tens of MiB, and they publish progress events as the bytes move. Every guest result carries transport (psdirect or ssh); see client configuration for the optional SSH transport, which stays unused until guest_ssh_provision has set it up. guest_report(what="transport") says which transport a VM is on and, with probe=true, times one trivial command over the path the next call would use; guest_transport saves a per-VM choice (auto/psdirect/ssh) that applies to the next call, and a HYPERV_MCP_GUEST_TRANSPORT_<VM> variable still wins over it.
The files family is the browsing half of the same job: file_roots names the four host roots and whether each exists, host_list_dir/host_make_dir/host_rename/host_delete work inside one of them (a path is resolved and refused if it lands outside its root, so .. and an absolute path both fail), and guest_list_dir/guest_make_dir/guest_rename/guest_delete do the same inside the VM over the configured transport. Deleting anything needs the path spelled back in confirm_path; a non-empty directory needs recursive=true as well. The dashboard draws this as two panels; the tools exist so an agent can do it too.
The guest password lives in the current user's Windows Credential Manager under HyperVConsoleMCP/<vm>, so it never has to sit in the MCP host environment. guest_autologon_configure then makes the VM boot straight to the desktop: the password goes into LSA private data rather than the registry, and the no-lock-screen, no-Ctrl+Alt+Del, power, UAC and update-reboot toggles each record the value they replaced in the guest's C:\DriverLab\State\guest-config.json, which guest_config_revert restores. guest_credential_status reports which source is in use and whether PowerShell Direct and SSH accept it without returning the secret; guest_credential(action="rotate") changes the password in the guest, proves a fresh session accepts it and only then replaces the stored one. The HYPERV_MCP_GUEST_USERNAME/HYPERV_MCP_GUEST_PASSWORD pair still works as a fallback.
Media operations use an existing DVD drive and require the VM to be Off. media_mount(..., boot_first=true) changes firmware/BIOS boot priority; it does not start the VM. Serial attachment requires an already configured COM1 named pipe and a Running VM. It is not a WinDbg replacement and cannot be combined with a debugger that already owns that pipe.
Dashboard and reproducible lab
Start the native dashboard with python -I scripts\run_dashboard.py or, after installation, hyperv-dashboard. --vm <name> picks the VM up front; without it the window opens the fleet and asks from a list when there is more than one, so no VM name is built into the program. It uses the same service and policies as MCP and exposes a fleet page, a multi-VM matrix page, workspace tabs, the activity, console, checkpoint, recovery, media, serial/debugging, guest, lab and file-manager pages, a live log dock along the bottom that follows the unified stream with filters for VM, source and level, a search box, pause and correlation grouping, and a real terminal (xterm) over guest_exec on the Guest page. It does not rebuild Hyper-V Manager: the fleet's Hyper-V Manager button and the console's Open VMConnect button start Windows' own tools, and a file can be dragged from one panel of the file manager to the other. Optional per-request approval of AI mutations is documented in the dashboard guide; a pending request is a card in a side queue, never a modal prompt, so the window stays usable while an operation waits.
hyperv-console-mcp on its own is the same window, and that is the command the Start Menu shortcut runs: a terminal gets the window, an MCP client — which always gives the process a pipe — gets the server, and a shortcut started with no stdin gets the window too. --stdio and --ui say which one you meant; --vm NAME and --classic are handed to the window unchanged.
hyperv-tray (pip install hyperv-console-mcp[tray]) puts the window in the notification area: Open starts it, Status reports the host, Quit closes the icon. Its tooltip carries the live line — 3 VMs · 2 running · lab profile, or why the service is not answering — so a host that stopped answering is visible without opening anything. It is a client of the same service, keeps no state of its own, and names no VM on the tooltip.
The window is a WebView2 page (pip install hyperv-console-mcp[ui], or pywebview already present). It is one HTML file with every asset inline — the page as written, plus the vendored xterm it inlines when it is read — so it starts no local HTTP server and opens no port. The same file can be opened in the operator's own browser with hyperv-console-mcp --serve: the listener binds 127.0.0.1, prints a URL carrying a token generated for that run, and requires it on every request, with Origin/Host checks against DNS rebinding; the page speaks the same calls to the same service, so nothing about the policy changes. See the dashboard guide and the listener's own section in SECURITY.md. It has a light and a dark theme — following the system until the operator switches it, with the choice kept in the window's own storage and never sent to the service — and every control is reachable by keyboard, including the workspace tabs, the console and the receipt rows. On a host without the WebView2 runtime or without pywebview, hyperv-dashboard opens the tkinter window instead of failing; --classic asks for that window on any host.
A host where no VM has a level yet opens on a three-question wizard — which VM, what the AI may do with it, and the guest password once — instead of sending a first-time operator to a config file. It writes the same access file the Overview page writes and stores the password through the service, so it grants nothing extra; it stops opening by itself as soon as one VM has a level, and Set up another VM on the fleet brings it back. See the dashboard guide.
The MCP server and the dashboard are clients of one background service, so a KD or serial session the AI opens is the session the window shows, and the activity page lists what the other process did. Alongside the operation events, logs_subscribe reads one structured log stream — timestamp, source (worker, kd, serial, ssh, wmi, lab, service), VM, level, correlation id and a redacted message — from an offset, with filters and the same held-open shape as events_wait, so a window can show the AI and the operator working side by side instead of polling. Every operation writes a started and a completed/failed line under the correlation id its events carry, and a line never carries a command, typed text or a secret: the message is scrubbed before it is stored, so what a reader gets back is what the file holds. A client that finds no host starts one (hyperv-service, or hyperv-service --pipe NAME) and joins it; HYPERV_MCP_SHARED_SERVICE=false keeps a private copy for a run that must not disturb a live one, and HYPERV_MCP_SERVICE_PIPE names a different pipe. The host reads its policy once at startup, so whichever client starts it decides the environment for both — set the level per VM in the access file rather than relying on a client's environment.
The lab workflow initializes fixed guest directories, stages hash-verified packages and collects evidence. Package sources and evidence downloads are confined to HYPERV_MCP_LAB_ROOT and HYPERV_MCP_EVIDENCE_ROOT. Running a package is refused outside HYPERV_MCP_PROFILE=lab; in that profile lab_run/lab_cycle run it, checkpoint first, and classify the outcome as ok, failed, not_verified, bugcheck, hang or timeout. A bugcheck is then triaged from the dump the run collected — the newest minidump first, !analyze -v through kd, merged with the host's own crash record — and each cycle writes lab-cycle.json beside the evidence so two runs of the same package can be diffed. lab_receipts reads those records back on the host alone — action="list" names every run newest first, action="get" returns one run with the host path and SHA-256 of each evidence file, action="compare" reports field by field what changed between two runs, marking a field one side never had as absent rather than as changed to nothing, and action="export" copies every receipt into one JSON document under exports/ without moving the originals. lab_cycle(record=true) keeps a GIF of the guest console as evidence; lab_matrix runs the same package on two to four VMs, one after another with a run id per VM, and returns the rows plus a field-by-field comparison so the difference is a column rather than a memory. lab_verifier turns Driver Verifier on for named test drivers and lab_driver_service installs, starts, stops and removes a test kernel-driver service, both recorded and revertible in the guest; a refused driver is reported with its Win32 error and NTSTATUS, and signature enforcement is never bypassed. See the lab guide; no driver or mapper is bundled or run by this repository.
Performance and debugging
The server reuses one local PowerShell worker for host and console work and a second one for guest operations, so a long guest_exec does not stall vm_get or console input. Inside each worker it keeps one PowerShell Direct session per VM, so a guest request does not pay for a new remoting connection. An upload uses Copy-VMFile when the guest's Guest Service Interface is enabled and falls back to Copy-Item -ToSession otherwise; downloads use Copy-Item -FromSession, since Copy-VMFile only goes host to guest. Every copy is SHA-256 verified on the far side. The fake-worker benchmark measures startup and warm requests without Hyper-V; it is not presented as a live VM benchmark. PowerShell Direct remains the default for isolated guests. Optional SSH is appropriate only for frequent guest administration on an intentionally configured isolated network.
For kernel work, choose KDNET after reviewing a suitable network path, or COM1/named pipe to preserve a no-network VM. Guest BCD and host COM1 preparation are separate, explicitly confirmed operations. Neither stops nor reboots the VM automatically.
kd_attach then drives a real kd.exe from the server: one session per VM, a per-session marker that delimits every command's output (never a sleep), an explicit disconnected → waiting_for_target → running ↔ broken state reported by kd_status, break-in through the console with vm_inject_nmi as the fallback, and a full log under %LOCALAPPDATA%\HyperVConsoleMCP\kd\<vm>\. debug_setup(transport="kdnet", action="prepare") sets up the internal lab switch, a UDP port in 50000–50039 and a host firewall rule that names kd.exe; the generated key lives only in the Windows Credential Manager and is masked in everything the tool returns. Symbols come from the Microsoft symbol server into a local cache, plus any staged lab package that ships a .pdb. In the lab profile, lab_cycle(..., debugger="kdnet") attaches kd before the run, arms sxe ld:<driver> for each .sys in the package manifest, and reports a bugcheck with the parsed !analyze -v instead of calling it a hang, together with whether the test driver's symbols actually resolved.
Security boundaries
Local stdio by default; no unauthenticated listener. The only port this project can open is
--serve:127.0.0.1only, a token generated per run and required on every request,Origin/Hostchecks against DNS rebinding, andCache-Control: no-store.Read-only mode by default; allowlist required for every mutation.
The approval gate decides whether a tool call may proceed; it is not a sandbox. It does not protect against an agent that already has a shell on the host, and the lab profile deliberately gives an autonomous loop full control of the allowlisted VMs.
HYPERV_MCP_PROFILE=labenables every capability for the allowlisted VMs and skips the per-mutation dashboard approval. It does not widen the allowlist, skip aconfirm_*field, or stop the audit and event records; an explicitHYPERV_MCP_ALLOW_*=falsestill wins.lab_run/lab_cycle, which execute a staged package, exist only in this profile.Console input is real input to the VM and can change state immediately.
The
kd_*tools follow the same allowlist and requireHYPERV_MCP_ALLOW_DEBUGGER; the KDNET key is generated on the host, stored in the Windows Credential Manager and masked in every result. The host-side KDNET change is one firewall rule forkd.exeon one UDP port of the internal lab switch — never an external switch.Screenshots may contain sensitive guest information and are gated separately.
Audit events contain timestamp, operation, VM, outcome, and error code only. Guest commands, typed text, passwords, and file contents are excluded.
A guest-command timeout may leave that command running; inspect before retrying.
Checkpoint restoration and deletion can discard data; the server does not make them implicit recovery steps.
This project does not manage BYOVD, load drivers, or treat debugger configuration as authorization to run a payload.
See security policy and project journal for implementation decisions and current limitations.
Development
python -m pytest
python -m buildCI runs the suite on Windows 3.11/3.12/3.13 with ruff, PowerShell parsing and PSScriptAnalyzer, the MCP smoke and the build, and runs the unit suite on Linux, where the Windows-only tests skip themselves. tests/test_secrets.py also scans a deliberately leaking build, so a scan that cannot turn red fails the run instead of passing quietly.
The PowerShell bridge accepts fixed operations and JSON over stdin, not generated PowerShell source. The fake bridge allows transport tests without Hyper-V. Live testing must be separately authorized and restricted to a disposable VM.
For an elevated, read-only end-to-end diagnostic through a real MCP stdio client:
python -I tests\live_mcp_readonly.py --vm NORTH-TestThis queries host, VM, console, COM/debugger status, media, and checkpoints. It does not change VM or guest state.
Live checks that do mutate a VM exist as separate scripts and never run in the pytest suite. Each reads HYPERV_MCP_LIVE_TEST_VM (or --vm) and expects a disposable guest:
Script | What it proves |
| host, VM, console and debugger status, no changes |
| the same through a real MCP stdio client |
| a real host in another process, an MCP client over its pipe, and a second client reading the events the first produced |
| SSH provisioning, transport round trip, deprovision |
| atomic package staging, host-side verification and the publish refusal |
| autologon + toggles, thumbnail screenshot, revert |
| KDNET or serial attach → break → stack → detach |
|
|
| a ~100 KB |
| the session is reused, |
| the file manager: a folder on each side, a file copied both ways with matching digests, the progress events, and a delete refused without its confirmation |
License
MIT — see LICENSE.
Available Tools
44 toolscheckpoint_createBDestructive
Create a manual checkpoint. Requires ALLOW_CHECKPOINTS and an allowlist.
Inputs: name (required), vm_name (required). Returns: object
checkpoint_deleteADestructive
Delete one checkpoint and merge its disks. Child checkpoints are not recursively included. Requires exact confirmations.
Inputs: vm_name (required), confirm_vm (required), snapshot_id (required), confirm_snapshot_id (required). Returns: object
checkpoint_listBRead-onlyIdempotent
List checkpoint IDs, names, parents, and creation times.
Inputs: vm_name (required). Returns: object
checkpoint_restoreADestructive
Restore a checkpoint, discarding later guest state. confirm_vm and confirm_snapshot_id must match exactly.
Inputs: vm_name (required), confirm_vm (required), snapshot_id (required), confirm_snapshot_id (required). Returns: object
console_batchADestructive
Run up to 32 ordered text, key-chord, click, move, scroll, wait, or Ctrl+Alt+Delete actions. Stops at the first failure.
Inputs: actions (required), vm_name (required). Returns: object
console_clickCDestructive
Click left, right, or middle. Optionally move to guest-display x/y first.
Inputs: vm_name (required), x, y, button. Returns: object
console_ctrl_alt_deleteBDestructive
Send the Hyper-V secure-attention sequence to the guest.
Inputs: vm_name (required). Returns: object
console_infoBRead-onlyIdempotent
Read guest video-head resolutions for mouse coordinate planning.
Inputs: vm_name (required). Returns: object
console_key_stateADestructive
Explicitly press or release one supported key. Release held keys when finished; prefer console_press_keys for ordinary chords.
Inputs: key (required), down (required), vm_name (required). Returns: object
console_mouse_buttonsBDestructive
Set explicit left, right, and middle synthetic-mouse button states for drag operations.
Inputs: vm_name (required), left, right, middle. Returns: object
console_mouse_moveBDestructive
Move the synthetic mouse to absolute guest-display pixel coordinates, not host-window coordinates.
Inputs: x (required), y (required), vm_name (required). Returns: object
console_press_keysBDestructive
Press and release a key chord (for example ['ctrl','s'] or ['enter']) using Hyper-V virtual-key codes.
Inputs: keys (required), vm_name (required). Returns: object
console_screenshotARead-onlyIdempotent
Experimental PNG capture of an existing visible VMConnect window in the MCP server's interactive session. It does not read the guest framebuffer. Requires ALLOW_SCREENSHOTS and an allowlist.
Inputs: vm_name (required), region, max_width.
console_scrollCDestructive
Apply a relative synthetic-mouse wheel delta. Positive values normally scroll up.
Inputs: delta (required), vm_name (required). Returns: object
console_type_textADestructive
Type printable ASCII, tab, CR, or LF through Msvm_Keyboard. Unicode/ABNT2 text is rejected; use guest_exec for Unicode and match the guest keyboard layout. No VMConnect focus is required.
Inputs: text (required), vm_name (required). Returns: object
debug_guest_prepareADestructive
Enable fixed COM1/115200 guest BCD debugging through PowerShell Direct while the VM is Running. Requires ALLOW_DEBUGGER, guest credentials, and confirm_vm. A deliberate later reboot is required.
Inputs: vm_name (required), confirm_vm (required). Returns: object
debug_serial_prepareADestructive
Configure COM1 kernel debugging over a local named pipe while the VM is Off. Guest BCD settings are a separate Running-VM operation. Never stops or reboots automatically. Requires ALLOW_DEBUGGER and confirm_vm.
Inputs: vm_name (required), pipe_name (required), confirm_vm (required). Returns: object
debug_serial_statusBRead-onlyIdempotent
Read Hyper-V COM port debug configuration and local WinDbg/KDNET availability.
Inputs: vm_name (required). Returns: object
events_snapshotBRead-onlyIdempotent
Read recent operation lifecycle events from this MCP instance, without commands, passwords, typed text, or file contents.
Inputs: after_sequence. Returns: object
guest_eventsBRead-onlyIdempotent
Read recent System, Application, Security, or Setup event records with optional event ID and level filters.
Inputs: vm_name (required), hours, level, event_id, +2 more. Returns: object
guest_execBDestructive
Run PowerShell in the guest through PowerShell Direct. Credentials come only from the server environment. Returns combined output, exit code, and truncation status. A host-side timeout may leave the guest command running.
Inputs: command (required), vm_name (required). Returns: object
guest_processesARead-onlyIdempotent
List up to 200 guest processes, optionally filtered by process name. Requires ALLOW_GUEST and guest credentials.
Inputs: vm_name (required), name_contains. Returns: object
guest_read_fileARead-onlyIdempotent
Read an absolute guest file path as base64, with SHA-256. Default limit 64 KiB; maximum 8 MiB. For large files, request bounded chunks through the lab APIs rather than inflating model context.
Inputs: vm_name (required), guest_path (required), max_bytes. Returns: object
guest_servicesARead-onlyIdempotent
List up to 200 guest services filtered by name; stopped services are excluded by default.
Inputs: vm_name (required), name_contains, include_stopped. Returns: object
guest_statusARead-onlyIdempotent
Read guest OS, boot time, memory, system-drive free space, and kernel debug settings through PowerShell Direct.
Inputs: vm_name (required). Returns: object
guest_write_fileADestructive
Write base64 content to an absolute guest path. Existing files require overwrite=true and confirm_path equal to guest_path.
Inputs: vm_name (required), guest_path (required), content_base64 (required), overwrite, +2 more. Returns: object
hyperv_host_statusARead-onlyIdempotent
Read Hyper-V host and service health.
Inputs: no named parameters. Returns: object
lab_collectBDestructive
Collect a new run's logs, events, diagnostics and dumps into HYPERV_MCP_EVIDENCE_ROOT. A kernel dump is opt-in; no new test is started.
Inputs: run_id (required), vm_name (required), package_id (required), include_kernel_dump. Returns: object
lab_diagnosticsBRead-onlyIdempotent
Read guest boot, Secure Boot, VBS/HVCI, test-signing, debugger, disk, and crash-dump configuration.
Inputs: vm_name (required). Returns: object
lab_initBDestructive
Install or verify fixed lab tools in C:\DriverLab and create package/run/evidence directories. Never executes a payload. Requires confirm_vm.
Inputs: vm_name (required), confirm_vm (required). Returns: object
lab_stageADestructive
Stage a hash-verified package from a subdirectory of HYPERV_MCP_LAB_ROOT. Supports chunked large files and never executes staged content.
Inputs: vm_name (required), source_directory (required), package_id. Returns: object
lab_verifyBRead-onlyIdempotent
Re-verify all package files and the exact manifest SHA-256 in the guest without executing the package.
Inputs: vm_name (required), package_id (required), expected_manifest_sha256 (required). Returns: object
media_ejectADestructive
Eject an existing VM DVD drive while the VM is Off. Requires ALLOW_MEDIA and confirm_vm equal to vm_name.
Inputs: vm_name (required), confirm_vm (required), controller_location (required), controller_number. Returns: object
media_listBRead-onlyIdempotent
List VM DVD drives, mounted ISO paths, controller locations, generation, and power state.
Inputs: vm_name (required). Returns: object
media_mountADestructive
Mount an existing host ISO in an existing VM DVD drive while the VM is Off, optionally making it first boot device. Never stops the VM automatically. Requires ALLOW_MEDIA and confirm_vm equal to vm_name.
Inputs: vm_name (required), iso_path (required), confirm_vm (required), controller_location (required), +2 more. Returns: object
serial_connectADestructive
Attach a dedicated reader to the existing COM1 named pipe of a Running VM and append output to a local .log file. Requires ALLOW_DEBUGGER and confirm_vm; does not configure the port or guest.
Inputs: vm_name (required), log_path (required), pipe_name (required), confirm_vm (required). Returns: object
serial_disconnectADestructive
Detach this server's serial reader and close its pipe handle without changing the VM COM port.
Inputs: vm_name (required). Returns: object
serial_readARead-onlyIdempotent
Read the retained tail of an attached serial console. Requires ALLOW_DEBUGGER.
Inputs: vm_name (required), tail_chars. Returns: object
serial_sendBDestructive
Write UTF-8 text to an attached COM1 serial console, with CRLF appended by default.
Inputs: text (required), vm_name (required), append_newline. Returns: object
serial_statusBRead-onlyIdempotent
Read COM1 configuration and whether this server has an attached serial-console reader.
Inputs: vm_name (required). Returns: object
vm_getARead-onlyIdempotent
Get VM state, devices, memory, network, and checkpoint count.
Inputs: vm_name (required). Returns: object
vm_listARead-onlyIdempotent
List VMs visible through the optional allowlist.
Inputs: no named parameters. Returns: object
vm_powerADestructive
Start, gracefully shut down, save, pause, resume, forcibly turn off, or reset a VM. turn_off/reset require confirm_vm equal to vm_name. Requires ALLOW_POWER and an allowlist.
Inputs: action (required), vm_name (required), confirm_vm. Returns: object
vm_waitARead-onlyIdempotent
Poll until a VM reaches one of the requested states. Returns matched=false on timeout and never changes power state.
Inputs: states (required), vm_name (required), timeout_seconds, poll_interval_ms. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 44 tools
Most tools target distinct Hyper-V objects and actions, with category prefixes that help separate VM, checkpoint, guest, console, media, serial, debug, and lab operations. A few boundaries could still confuse an agent, such as guest_status versus lab_diagnostics, console_key_state versus console_press_keys, and serial_status versus debug_serial_status, but descriptions generally clarify them.
Names consistently use snake_case and mostly follow a domain-prefixed action pattern such as vm_list, checkpoint_create, guest_exec, media_mount, and console_click. Minor deviations like hyperv_host_status and events_snapshot exist, but the overall convention is readable and predictable.
At 44 tools, the surface is heavy for a single MCP server and spans many subdomains: VM lifecycle, checkpoints, guest OS access, console input, media, serial, debugging, and lab workflows. While each tool may be useful, the count is well above a well-scoped set and raises selection overhead.
The server covers a broad lifecycle: VM listing/status/power/wait, checkpoints, guest execution and files, console control, media mounting, serial access, debugging, and lab evidence collection. Some notable gaps remain, such as VM creation/deletion/cloning and virtual network/switch management, but most core lab-console workflows are covered.
Maintenance
Related MCP Connectors
Securely control computers you explicitly pair through files, terminals, processes, screenshots, desktop UI/input, clipboard, browser automation, diagnostics, and document tools.
MCP server for Superserve sandboxes: create, exec, and manage Firecracker microVMs
Control your authorized Windows computers via OAuth: files, shell, apps, and task status.
Linux server administration over OAuth MCP: shell, Docker, systemd, files and monitoring.
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server for controlling a Windows guest VM over WinRM, enabling PowerShell/CMD execution, file transfer, reboot, and KDNET debug configuration, typically paired with kd-mcp.12MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to safely test and debug PowerShell, CMD/BAT scripts, and system utilities inside isolated Hyper-V virtual machines, with snapshot rollback, host-to-guest file transfer, PowerShell Direct execution, and autonomous self-correction on failures.1Apache 2.0
- FlicenseNot gradedqualityCmaintenanceEnables controlled Hyper-V virtual machine operations over MCP, including status queries, checkpoints, in-guest command execution, and file transfers, without requiring guest networking or WinRM.1-
- AlicenseNot gradedqualityBmaintenanceEnables a trusted operator to drive a Windows workstation remotely over OAuth-protected Streamable HTTP, running PowerShell commands and file edits with checkpoints, durable jobs, and native service support.MIT