# qemu-mcp

An MCP server for Claude Code lets an agent boot and control QEMU virtual machines. It can load an ISO or kernel, send keyboard input, and inspect the display or serial console.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 5 repo stars
- Author: 0xmortuex
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/0xmortuex/qemu-mcp
- Updated: 2026-11-16
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/mcp/qemu-mcp

## What it does

qemu-mcp starts QEMU without a graphical window and exposes controls for the guest VM. An agent can boot an ISO, kernel, or disk, press keys, enter text, capture the display, and read or write serial-console data. It can also wait for a chosen string in serial output, such as a kernel-ready marker.

The guest does not need an agent or network connection; control goes through QEMU. QEMU and `uvx` are needed to run the server, while disk creation uses the separate `qemu-img` tool. VM snapshots are supported, and saving one requires a qcow2 disk.

## Requirements
- Needs: Python and uv (commands run via uvx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add qemu-mcp -- uvx qemu-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from qemu-mcp <command>

### Codex

**Platform CLI**
```bash
codex mcp add qemu-mcp -- uvx qemu-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from qemu-mcp <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "qemu-mcp": {
            "command": "uvx",
            "args": [
                "qemu-mcp"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from qemu-mcp <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "qemu-mcp": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "qemu-mcp"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from qemu-mcp <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add qemu-mcp uvx qemu-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from qemu-mcp <command>

## When to use it
- boot an ISO or kernel in QEMU to test startup
- send keyboard input to a virtual machine
- capture a guest display without opening a GUI
- wait for a boot marker in serial output

## Example prompts
- Boot `build/kernel` in QEMU and show me a screenshot.
- Press `Esc`, type `help`, then read the serial console output.
- Start the VM and wait for `kernel ready` on the serial console.

## Similar
- [qemu-for-kernel-development](https://affpapa.org/en/nevibecode/skills/qemu-for-kernel-development.md) — skill · 419 installs
- [qemu-embedded-simulation](https://affpapa.org/en/nevibecode/skills/qemu-embedded-simulation.md) — skill · 389 installs
- [mcp-proxmox](https://affpapa.org/en/nevibecode/mcp/mcp-proxmox.md) — MCP server · ★ 17 repo stars
- [GuestKit](https://affpapa.org/en/nevibecode/mcp/guestkit.md) — MCP server · ★ 9 repo stars
- [Proxmox VE](https://affpapa.org/en/nevibecode/mcp/gethosthewalrus-proxmox-ve.md) — MCP server
- [proxmox](https://affpapa.org/en/nevibecode/skills/proxmox.md) — skill · 1 install

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
