Skip to main content
Glama

qemu-mcp

MCP server for controlling QEMU over QMP and the human monitor. The control loop is text-first: capture the screen as OCR text or ASCII, send keys and text, and keep raw PNG screenshots for when a vision model or a human needs to look.

qemu-mcp session in OpenCode

What it does

  • Starts, resets, and stops QEMU from an MCP client.

  • Reads the guest screen as OCR text, ASCII, or PNG.

  • Types text and sends key sequences.

  • Moves the mouse and changes button state.

  • Creates qcow2/raw/VMDK/VDI/VPC disks with qemu-img.

  • Lists and reads FAT12/FAT16 images; builds FAT16 images.

  • Runs named macros from scripts/mcp/macros/.

  • Exposes raw monitor commands and QMP calls when the typed tools are not enough.

Related MCP server: qemu-mcp-server

Requirements

  • Node.js 20 or newer.

  • QEMU with qemu-system-i386 and qemu-img.

  • An OCR engine for screen_text and wait_for_text:

    • Windows: the built-in Windows OCR engine via PowerShell.

    • Linux and macOS: Tesseract (tesseract on PATH).

    • screen_ascii and screenshot work without OCR.

QEMU defaults to C:\Program Files\qemu\qemu-system-i386.exe. Set these to override it:

Variable

Default

Purpose

QEMU_BIN

C:\Program Files\qemu\qemu-system-i386.exe

QEMU system binary

QEMU_IMG

next to QEMU_BIN

qemu-img binary

QEMU_DISK

./vm/disk.qcow2

default disk when vm_launch omits disk

QEMU_MONITOR_PORT

5555

QMP monitor port

QEMU_MCP_MACROS

bundled scripts/mcp/macros

macro directory override

QEMU_MCP_OCR

auto

auto, windows, or tesseract

QEMU_MCP_TESSERACT

tesseract

Tesseract binary

QEMU_MCP_OCR_LANG

eng

Tesseract language

QEMU_MCP_OCR_PSM

6

Tesseract page segmentation mode

Install Tesseract:

# Ubuntu / Debian
sudo apt install tesseract-ocr

# Fedora
sudo dnf install tesseract

# macOS
brew install tesseract

Windows uses its built-in OCR engine; no extra package is required.

Install

Global install from GitHub:

npm install -g github:onionbutties/qemu-mcp
qemu-mcp --version

Run without installing:

npx -y github:onionbutties/qemu-mcp

From a clone:

git clone https://github.com/onionbutties/qemu-mcp.git
cd qemu-mcp
npm install
node scripts/mcp/server.mjs

The server uses its process working directory for the default disk (./vm/disk.qcow2) and for relative paths passed to vm_create_disk, vm_launch, fat_*, and the macros. In a global MCP config, set the client's working directory to the project that owns the VM, or pass absolute paths. Clients that do not expose a working directory setting should use absolute paths or QEMU_DISK.

Client setup

OpenCode

Global:

opencode mcp add qemu --global -- qemu-mcp

Project config (.opencode/opencode.json or opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "qemu": {
        "type": "local",
        "command": ["qemu-mcp"],
        "cwd": "."
      }
    }
  }
}

Without a global install, use npx:

opencode mcp add qemu --global -- npx -y github:onionbutties/qemu-mcp

Claude Code

Global user scope:

claude mcp add --scope user qemu -- qemu-mcp

Without a global install:

claude mcp add --scope user qemu -- npx -y github:onionbutties/qemu-mcp

Project scope writes .mcp.json:

claude mcp add --scope project qemu -- qemu-mcp

Codex

Add to ~/.codex/config.toml:

[mcp_servers.qemu]
command = "qemu-mcp"
args = []

With npx:

[mcp_servers.qemu]
command = "npx"
args = ["-y", "github:onionbutties/qemu-mcp"]

Cursor

Add to ~/.cursor/mcp.json for all projects, or .cursor/mcp.json for one project:

{
  "mcpServers": {
    "qemu": {
      "type": "stdio",
      "command": "qemu-mcp",
      "args": []
    }
  }
}

With npx:

{
  "mcpServers": {
    "qemu": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "github:onionbutties/qemu-mcp"]
    }
  }
}

Gemini CLI

Global user scope:

gemini mcp add -s user qemu qemu-mcp

Without a global install:

gemini mcp add -s user qemu npx -- -y github:onionbutties/qemu-mcp

Other MCP clients

Any client that supports local stdio servers can launch qemu-mcp with no arguments. The server speaks MCP on stdin/stdout and writes diagnostics to stderr only.

Tools

Tool

Purpose

vm_status

Running state, PID, monitor port, disk, last error

vm_create_disk

Create a disk with qemu-img (qcow2, raw, vmdk, vdi, vpc)

vm_launch

Start QEMU; the disk must exist

vm_quit

Stop QEMU

vm_reset

Reset the running guest

send_key

Send a QEMU key sequence such as ret or ctrl-alt-del

type_text

Type ASCII text

press

Press a key sequence, optionally with a hold time

mouse_move

Move the mouse by a relative delta

mouse_button

Set button state; bitmask 1 left, 2 right, 4 middle

monitor_command

Run a human monitor command

qmp_execute

Run a QMP command with JSON arguments

screenshot

Capture a PNG and return it as MCP image content plus a path

screen_text

Capture and OCR the screen

screen_ascii

Capture and render the screen as ASCII, with optional crop

wait_for_text

Poll until text or a regex appears

fat_list

List a FAT12/FAT16 image

fat_read

Read a file; use encoding: "base64" for binary payloads

fat_build

Build a FAT16 image from host files

macro_list

List macros

macro_run

Run a macro by name

Example

vm_create_disk { path: "vm/disk.qcow2", sizeMb: 512, format: "qcow2" }
vm_launch      { disk: "vm/disk.qcow2", diskFormat: "qcow2", boot: "c" }
wait_for_text  { pattern: "C:\\>", timeoutMs: 30000 }
type_text      { text: "dir" }
press          { keys: "ret" }
screen_text
vm_quit

QEMU screen captured by the server

Screen output

screen_text returns OCR text from the current frame. screen_ascii returns a luminance rendering and accepts cols, rows, and crop (x, y, w, h). screenshot returns the PNG as MCP image content and leaves the file in vm/shots/mcp/.

OCR is useful for text-mode screens and dialog boxes. It is not reliable for icon-only toolbars, custom fonts, or damaged graphics. Use screenshot for those cases and pass the image to a vision model or a human.

Macros

Macros are ESM modules in scripts/mcp/macros/. Each module exports a default async function:

export default async function myMacro(session, args) {
  await session.command('sendkey ret');
  return { ok: true };
}

Set QEMU_MCP_MACROS to use a different directory. macro_run reloads the module when its mtime changes, so edits take effect without restarting the server.

Development

npm install
npm test

Tests cover the FAT reader, screen helpers, VM session locking, tool registration, raw text results, and the stdio server's tool catalog.

Limits

  • One VM session per MCP server process.

  • OCR quality depends on the engine and the guest's font rendering. Tesseract works best with clean, high-contrast text screens.

  • The server drives a GUI guest through keyboard and mouse; it does not provide pixel-level element lookup.

  • fat_build writes FAT16 only. fat_list and fat_read accept FAT12 and FAT16.

  • QEMU paths are configurable, but the default machine profile (machine.mjs) is a 32-bit PC with IDE, USB UHCI, and Sound Blaster 16 support.

License

MIT. See LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to control and automate Incus/QEMU virtual machines via SSH, supporting mouse/keyboard, screenshots, commands, and lifecycle management.
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Nido is a local QEMU VM manager. Install it on your computer from https://github.com/Josepavese/nido and run nido mcp via stdio, or use npx -y nido-mcp@latest mcp with QEMU installed locally. It manages VMs on that same computer; a server hosted by Glama cannot access your local VM inventory.
      6
      2
      MIT