What is mcqemu?
mcqemu is an MCP server that turns QEMU into tools an agent can call. It manages virtual machines on the machine it runs on: creating disks, booting them, watching their screens, typing into them, snapshotting them, running commands inside them, and tearing them down.
QEMU already speaks a machine-friendly protocol. QMP is JSON over a unix socket, and the guest agent speaks the same framing over a virtio-serial channel. Most of mcqemu is a careful mapping from that surface onto tools with names and descriptions written for the thing calling them.
What you can do with it
Section titled “What you can do with it”Boot an operating system from an installer ISO and drive the installation by looking at screenshots and sending keystrokes, without a display attached. Keep a base image around with the guest agent installed, then spin up disposable clones of it in seconds and destroy them when you are done. Freeze a running machine, try something destructive, and roll back to the exact moment before, memory included. Reach into a guest to run a command or drop in a file when there is no network and no credentials.
The pieces
Section titled “The pieces”A VM launched by mcqemu is a daemonized QEMU process with two unix sockets: one for QMP, one for the guest agent. A small JSON registry records what exists. Because the QEMU processes are daemonized, they outlive the MCP server, so restarting your editor does not take down your machines. See architecture for why that shape was chosen and what it costs.
Disk images are managed through qemu-img. Sandboxes are copy-on-write overlays
on top of a base image, which is what makes them cheap to create and safe to
throw away.
What it is not
Section titled “What it is not”It is not a cluster manager. There is no scheduler, no migration, no multi-host awareness; mcqemu manages VMs on one machine and says so.
It is not a hardened security boundary. A sandbox is a real VM with a separate kernel and no outbound network by default, which is a meaningful barrier against software that misbehaves, but it is not a claim that a determined attacker with a QEMU escape cannot get out. Sandboxing is explicit about where the line sits.
It does not require anything of a guest in order to watch or drive it. Screens
and keystrokes work at the firmware level. Only the guest_* tools need
cooperation, in the form of qemu-guest-agent running inside.
Where to go next
Section titled “Where to go next”The tutorial starts from nothing and ends with a working VM you can talk to. The tool reference lists every tool with its parameters. If you would rather understand the machinery first, start with architecture.