qemu-mcp
Controls QEMU virtual machines over QMP and the human monitor, including launching, resetting, and stopping VMs; capturing screen output as OCR text, ASCII, or PNG; sending keyboard and mouse input; creating and managing disk images; reading/building FAT images; running macros; and issuing raw monitor or QMP commands.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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.

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-i386andqemu-img.An OCR engine for
screen_textandwait_for_text:Windows: the built-in Windows OCR engine via PowerShell.
Linux and macOS: Tesseract (
tesseractonPATH).screen_asciiandscreenshotwork without OCR.
QEMU defaults to C:\Program Files\qemu\qemu-system-i386.exe. Set these to override it:
Variable | Default | Purpose |
|
| QEMU system binary |
| next to |
|
|
| default disk when |
|
| QMP monitor port |
| bundled | macro directory override |
|
|
|
|
| Tesseract binary |
|
| Tesseract language |
|
| Tesseract page segmentation mode |
Install Tesseract:
# Ubuntu / Debian
sudo apt install tesseract-ocr
# Fedora
sudo dnf install tesseract
# macOS
brew install tesseractWindows 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 --versionRun without installing:
npx -y github:onionbutties/qemu-mcpFrom a clone:
git clone https://github.com/onionbutties/qemu-mcp.git
cd qemu-mcp
npm install
node scripts/mcp/server.mjsThe 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-mcpProject 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-mcpClaude Code
Global user scope:
claude mcp add --scope user qemu -- qemu-mcpWithout a global install:
claude mcp add --scope user qemu -- npx -y github:onionbutties/qemu-mcpProject scope writes .mcp.json:
claude mcp add --scope project qemu -- qemu-mcpCodex
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-mcpWithout a global install:
gemini mcp add -s user qemu npx -- -y github:onionbutties/qemu-mcpOther 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 |
| Running state, PID, monitor port, disk, last error |
| Create a disk with |
| Start QEMU; the disk must exist |
| Stop QEMU |
| Reset the running guest |
| Send a QEMU key sequence such as |
| Type ASCII text |
| Press a key sequence, optionally with a hold time |
| Move the mouse by a relative delta |
| Set button state; bitmask |
| Run a human monitor command |
| Run a QMP command with JSON arguments |
| Capture a PNG and return it as MCP image content plus a path |
| Capture and OCR the screen |
| Capture and render the screen as ASCII, with optional crop |
| Poll until text or a regex appears |
| List a FAT12/FAT16 image |
| Read a file; use |
| Build a FAT16 image from host files |
| List macros |
| 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
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 testTests 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_buildwrites FAT16 only.fat_listandfat_readaccept 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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Linux VMs for AI agents: create VMs, run commands, edit files and open preview URLs.
Linux machines for AI agents: create, run commands, snapshot, fork, sandbox. Alpha.
Cloud desktops for AI agents: create a Linux computer, see its screen, click, type and run tasks.
Real desktops for AI agents, on machines you choose: screenshot, type, click, hire more agents.
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables AI agents to capture high-quality screenshots from running QEMU virtual machines using the QEMU Machine Protocol (QMP), automatically discovering VMs and returning screenshots as PNG images.1-
- AlicenseNot gradedqualityCmaintenanceAn MCP server that gives AI agents direct control over QEMU virtual machines.25 npm1MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to control and automate Incus/QEMU virtual machines via SSH, supporting mouse/keyboard, screenshots, commands, and lifecycle management.MIT
- AlicenseBqualityBmaintenanceNido 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.62MIT