Qemu MCP

qemu-mcp

Let your AI agent boot an operating system and drive it.

qemu-mcp is an MCP server that gives AI agents (Claude Code, or any MCP client) hands on a QEMU virtual machine: boot an ISO or a raw kernel, press keys, take screenshots, read the serial console, and wait for boot markers — all headless, with zero cooperation from the guest. No SSH, no guest agent, no network. If it boots in QEMU, an agent can drive it.

*This screenshot was taken by an AI agent: it booted MORT OS (a hobby kernel with no SSH, no agent, no TCP required) headless, pressed Esc, typed help, and captured the framebuffer — four tool calls.*

Who this is for

OS developers and hobby kernel hackers. The osdev inner loop is: edit kernel → build → boot in QEMU → *look at the screen* → type something → read serial → repeat. An AI agent can already do the edit and build steps; qemu-mcp gives it the rest of the loop, so it can boot-test its own kernel changes and actually see the triple fault.

It's equally useful for anyone who needs an agent to poke at a VM below the OS level: bootloaders, installers, BIOS/UEFI menus, recovery consoles, firmware.

Why another QEMU MCP server?

The existing ones assume a *full, running guest OS* — they exec commands over SSH or a guest agent. That's useless when your guest is a 40 KB kernel you wrote yourself, an installer ISO, or anything pre-boot. qemu-mcp is built for the boot-test loop instead:

• Serial console capture — continuously logged to a file, readable at any time (qemu_serial), and writable too (qemu_serial_send)
• `qemu_wait_serial` — block until "kernel ready" (or "login:", or your panic string) appears, the reliable way to sequence an automated boot test
• `-kernel` boot — boot a multiboot/bzImage kernel directly, with append/initrd
• Screenshots of the VGA framebuffer — works headless, shows exactly what a monitor would
• Raw QMP escape hatch — the full QEMU Machine Protocol when you need memsave, system_reset, device_add…

Tools

Multiple named VMs can run at once.

Every tool declares all four MCP behaviour hints, so your client knows which calls to confirm with you. Only the waiting and reading tools (qemu_screenshot, qemu_serial, qemu_wait_serial, qemu_wait_screen, qemu_snapshot_list, qemu_version, qemu_machines, qemu_cpu_models) are read-only. qemu_boot and qemu_list are marked destructive because they clean up VMs that exited on their own, deleting their serial logs; read a crashed guest's output with qemu_serial first. qemu_boot and qemu_qmp are open-world: extra_args and raw QMP can reach anything QEMU can.

Install

Requirements: Python 3.10+, and QEMU on your PATH (on Windows, C:\Program Files\qemu is found automatically, or set QEMU_DIR).

pip install qemu-mcp

Claude Code:

claude mcp add qemu -- qemu-mcp

Any other MCP client (stdio transport):

{

"mcpServers": { "qemu": { "command": "qemu-mcp" } } }

Or without installing, via uv: claude mcp add qemu -- uvx qemu-mcp

Example session

you: boot build/os.iso and check the shell works

agent: qemu_boot(name="test", iso="build/os.iso", arch="i386") → booted

qemu_wait_serial(name="test", text="boot ok") → FOUND

qemu_type(name="test", text="help\n")

qemu_screenshot(name="test") → *sees the help output rendered*

qemu_stop(name="test", force=true)

"Your ISO boots, the shell responds to help, and the new command is listed. Screenshot attached."

A typical kernel test the agent can run by itself:

qemu_boot(name="k", kernel="build/kernel.elf", arch="i386",

extra_args="-device rtl8139,netdev=n0 -netdev user,id=n0") qemu_wait_serial(name="k", text="MORTNET READY", timeout_s=20) qemu_serial_send(name="k", text="net\n") # guest has no keyboard driver, only a serial shell qemu_serial(name="k") # did DHCP bind? qemu_screenshot(name="k") # what does the console show?

Non-x86 archs

x86_64 and i386 boot with no machine argument. Other archs have no default machine in QEMU and need -M set explicitly, or they'll fail to boot:

qemu_boot(name="a", kernel="build/kernel-aarch64.elf", arch="aarch64", machine="virt")

qemu_boot(name="r", kernel="build/kernel-riscv64.elf", arch="riscv64", machine="virt")

Run qemu_machines(arch="aarch64") for the full list of machines an arch supports — it reports qemu-system- -M help's own output without needing a shell.

virt has no default display device — unlike the PC-family boards x86_64/ i386 boot with, it doesn't wire up VGA on its own. qemu_screenshot/ qemu_wait_screen against a virt VM will see an empty/black framebuffer (or a QMP error, depending on QEMU version) unless the guest itself sets one up, which most bare-metal aarch64/riscv64 kernels don't. Add a display device explicitly if you need screenshots:

qemu_boot(name="a", kernel="build/kernel-aarch64.elf", arch="aarch64",

machine="virt", extra_args="-device virtio-gpu-pci")

(This is documented QEMU virt-board behavior, not verified against a real boot in this environment — no QEMU available here.)

Hardware acceleration

qemu_boot defaults to TCG (QEMU's software emulator) with no accel given - correct on any host, but a real slowdown for anything beyond a trivial kernel. Opt into your host's accelerator with accel, falling back to TCG if it's unavailable so the boot doesn't hard-fail on a host without it:

qemu_boot(name="fast", kernel="build/kernel.elf", accel="kvm:tcg")   # Linux

qemu_boot(name="fast", kernel="build/kernel.elf", accel="hvf:tcg") # macOS qemu_boot(name="fast", kernel="build/kernel.elf", accel="whpx:tcg") # Windows

If the requested accelerator genuinely isn't usable on the host (no /dev/kvm permission, virtualization disabled in firmware, etc.) QEMU itself reports why QEMU exited, and qemu_boot surfaces that in the error it raises.

CPU model

qemu_boot defaults to QEMU's own default CPU model for the arch/machine. Pass cpu (QEMU -cpu) to test guest code against a specific model or feature set instead:

qemu_boot(name="k", kernel="build/kernel.elf", cpu="qemu64,+avx")  # base model + one extra feature

qemu_boot(name="k", kernel="build/kernel.elf", cpu="max") # every feature QEMU/TCG can emulate qemu_boot(name="k", kernel="build/kernel.elf", accel="kvm", cpu="host") # pass the host CPU through under KVM

Run qemu_cpu_models(arch="x86_64") for the full list of models/features an arch supports — it reports qemu-system- -cpu help's own output without needing a shell.

CPU topology

smp alone sets a flat vCPU count. For guest code that cares about the socket/core/thread *shape* (ACPI MADT entries, CPUID topology leaves, per-socket vs. per-core scheduling), pass smp_cores/smp_threads/ smp_sockets/smp_maxcpus too - they're combined onto the same -smp flag:

qemu_boot(name="k", kernel="build/kernel.elf",

smp=8, smp_cores=