Skip to content
mcqemu

Install and connect

Requirements

Section titled “Requirements”

mcqemu drives local QEMU processes, so it runs where QEMU runs:

  • Linux, with qemu-system-x86_64 and qemu-img on your PATH. Other guest architectures need their own binary (qemu-system-aarch64 and so on).
  • Python 3.11 or newer, managed with uv.
  • Read and write access to /dev/kvm for hardware acceleration. This is optional: without it QEMU falls back to TCG software emulation, which works and is considerably slower.

Check the host before blaming the server:

Terminal window
qemu-system-x86_64 --version
qemu-img --version
ls -l /dev/kvm && test -w /dev/kvm && echo "kvm writable"

If /dev/kvm exists but is not writable, add yourself to the group that owns it (usually kvm) and log back in.

Install

Section titled “Install”

uvx downloads and runs the published package, with no install step to maintain:

Terminal window
uvx mcqemu

It prints a version banner to stderr and then waits for an MCP client on stdin. That is a healthy server; press Ctrl-C.

Register with Claude Code

Section titled “Register with Claude Code”

Pick the scope by asking who should get these tools.

Project scope writes .mcp.json in the repository, so anyone who checks it out gets the same server. Use this when VMs are part of the project’s workflow, such as a repository whose tests need a throwaway guest.

Terminal window
claude mcp add --scope project mcqemu -- uvx mcqemu

The resulting file, which you can also write by hand:

.mcp.json
{
  "mcpServers": {
    "mcqemu": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcqemu"],
      "env": {}
    }
  }
}

From a checkout, use "command": "uv" with "args": ["run", "--directory", "/path/to/mcqemu", "mcqemu"] so the server runs regardless of which directory Claude Code starts in.

Confirm it works

Section titled “Confirm it works”

  1. Run /mcp in Claude Code. mcqemu should be listed as connected. If it is listed as failed, run the exact command from your config in a terminal; the error is usually a missing uv on PATH or a wrong --directory.

  2. Ask the agent to call list_vms. A fresh install answers with an empty list and empty registry_warnings.

  3. Launch something disposable to prove QEMU itself works. Any ISO will do, and it does not need to boot anywhere useful:

    launch_vm(name="smoketest", iso="~/isos/alpine-virt.iso")

    The result reports accel: "kvm" or accel: "tcg", which tells you whether acceleration is active.

  4. Take a screenshot with vm_screenshot(name="smoketest"). If you get a PNG of a bootloader, every layer is working: the server, QEMU, and the QMP control channel.

  5. Clean up: stop_vm(name="smoketest", force=true). Force is appropriate here because no operating system is running to answer a power button press.

When something fails

Section titled “When something fails”

qemu-system-x86_64 not found on PATH. QEMU is not installed, or not for that architecture. On Arch, pacman -S qemu-full; on Debian and Ubuntu, apt install qemu-system-x86.

The launch result says accel: "tcg" and you expected KVM. Either /dev/kvm is not writable by your user, or the guest architecture does not match the host. KVM only applies when the two match; an aarch64 guest on an x86_64 host is always emulated.

A VM is running but no tool can see it. VMs survive restarts of the MCP server because they are daemonized QEMU processes, and the registry on disk is what connects them. If list_vms returns a non-empty registry_warnings, that bookkeeping was damaged and VMs may be running untracked. Find them with pgrep -af qemu-system before launching anything with the same name.

You want the state kept somewhere else. MCQEMU_STATE_DIR and MCQEMU_RUNTIME_DIR move the registry, logs and sockets; MCQEMU_LOG_LEVEL=DEBUG makes the server chattier on stderr. See Configuration.

Next

Section titled “Next”