Ryan Malloy
f4c2a70bbf
Starlight, diataxis-shaped: a tutorial pair, six how-to guides, a generated tool reference plus a configuration reference, and four explanation pages covering architecture, sandbox isolation, see-and-drive, and the failure handling philosophy. The tool reference is generated from the running MCP server's own schemas, so its 33 tools, parameters and defaults cannot drift from the code; the generator asserts its grouping still covers exactly the live tool set. Infrastructure follows the warehacking cookie-cutter (multi-stage Dockerfile, Caddy serving dist with real 404 status, compose profiles for prod and dev, Makefile with a deploy target pointed at docker-2). Two deviations worth noting: remark-gfm is added to the MDX pipeline because Astro enables GFM for .md but not .mdx, so tables silently rendered as run-together paragraphs; and the card icon palette is pinned to the accent because Starlight's staggered grid rotates through colours including purple. Package URLs now point at the Gitea repo and this site.
mcqemu
An MCP server that lets LLM agents manage QEMU virtual machines: launch and stop VMs, inspect them over QMP, manage disk images with qemu-img, take live snapshots, and run commands inside guests through qemu-guest-agent.
Requirements
- Linux with QEMU installed (
qemu-system-*andqemu-imgon PATH) /dev/kvmaccess for hardware acceleration (optional — TCG emulation works without it, just slower)- Python 3.11+ managed with uv
Install
# From this checkout
uv sync
# Add to Claude Code
claude mcp add mcqemu -- uv run --directory /path/to/mcqemu mcqemu
What it can do
| Group | Tools |
|---|---|
| Lifecycle | launch_vm, stop_vm, pause_vm, resume_vm, attach_vm, forget_vm |
| Sandboxes | sandbox_vm (overlay + launch + wait-for-agent in one call), sandbox_destroy |
| Inspect | list_vms, vm_info |
| Live snapshots | vm_snapshot_create / restore / delete / list |
| See & drive | vm_screenshot (PNG), vm_send_keys, vm_type_text, vm_click, vm_mouse_move (relative PS/2, for guests without tablet drivers), vm_serial_read |
| Disk images | image_create, image_info, image_convert, image_resize, image_snapshot_* |
| Guest agent | guest_ping, guest_info, guest_exec, guest_file_read, guest_file_write |
VMs are daemonized QEMU processes with QMP control sockets, so they survive
MCP server restarts. The registry lives in ~/.local/share/mcqemu/, sockets
in $XDG_RUNTIME_DIR/mcqemu/.
Guest tools (guest_*) need qemu-guest-agent installed inside the guest OS;
the host-side virtio-serial channel is wired on every launch, so installing
the agent in the guest is the only step.
Port forwards accept "2222:22" (explicit, collision-checked up front),
"auto:22", or just "22" — auto forms pick a free host port and the launch
result reports what was chosen.
Quick start
Disposable sandbox from any base image with qemu-guest-agent inside:
sandbox_vm(base_image="~/vms/ubuntu-agent.qcow2")
# -> overlay created, VM booted, agent waited for, free port forwarded to 22
guest_exec(name="sandbox", command="uname", args=["-a"])
sandbox_destroy(name="sandbox") # stops VM, deletes overlay; base untouched
Installing an OS from scratch:
image_create(path="~/vms/test.qcow2", size="10G")
launch_vm(name="test", disks=["~/vms/test.qcow2"], iso="~/isos/alpine.iso",
port_forwards=["auto:22"])
# ... drive the installer with vm_screenshot / vm_type_text / vm_send_keys ...
stop_vm(name="test")
launch_vm(name="test", disks=["~/vms/test.qcow2"])
guest_exec(name="test", command="uname", args=["-a"])
Development
uv run pytest # unit tests (QMP and subprocess mocked)
uv run pytest -m integration # acceptance: every tool group against real QEMU
uv run ruff check .
The acceptance suite boots real VMs. The guest-agent and snapshot journey
needs a base image with qemu-guest-agent installed — it looks for
~/vms/ubuntu-agent.qcow2, overridable with MCQEMU_TEST_BASE_IMAGE, and
skips cleanly when absent.