This server enables AI agents to capture screenshots from QEMU virtual machines via the Model Context Protocol (MCP), offering two primary tools:
capture_screenshot - Captures screenshots from already running QEMU instances by automatically discovering the first qemu-system-* process, using QMP for reliable window-independent capture (with X11 fallback), converting raw PPM output to PNG, and returning base64-encoded images with metadata.
run_and_screenshot (recommended for AI agents) - Provides atomic VM lifecycle management by starting a QEMU VM with specified architecture (x86_64/aarch64) and disk image, waiting for a configurable boot duration, capturing the screenshot, and performing clean shutdown. Supports custom QEMU arguments for memory, CPU, and acceleration settings.
Key Features:
Saves screenshots to
screenshots/directory with timestamped filenamesReturns detailed metadata including absolute file paths and base64-encoded PNG images
Comprehensive error handling for missing processes, QMP configuration issues, or connectivity problems
Requires QMP socket configuration for reliable operation
Includes mock server support for testing without actual QEMU instances
Provides tools for interacting with running QEMU virtual machine instances, including auto-discovery of QEMU processes and screenshot capture via the QEMU Machine Protocol (QMP).
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@QEMU Screenshot MCP Servercapture a screenshot of my running VM"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
QEMU Screenshot MCP Server
A Model Context Protocol (MCP) server that provides tools for interacting with running QEMU instances. Currently, it allows an agent to capture a high-quality screenshot of the first running QEMU virtual machine.
Features
🔍 Auto-discovery: Automatically finds the first running
qemu-system-*process.🔌 QMP Integration: Uses the QEMU Machine Protocol (QMP) for reliable, window-independent screenshot capture.
📁 Persistent Storage: Saves screenshots to a
screenshots/directory with timestamped filenames for easy access.🖼️ Auto-Conversion: Automatically converts QEMU's raw PPM output to PNG via Pillow for immediate use in AI interfaces.
🚀 Detailed Response: Returns the absolute file path and filename along with the base64-encoded PNG.
Installation
This server is designed to be used with uv for seamless execution.
Prerequisites
Python 3.12+
uvinstalled (pip install uv)A QEMU instance running with a Unix QMP socket.
QEMU Configuration
To use this server, your QEMU instance must expose a Unix QMP socket. Run QEMU with the following argument:
Configuration in Claude Desktop (or other MCP clients)
Add the following to your MCP configuration file (e.g., config.json for Claude Desktop):
Once you push your project to GitHub, you can replace the local path in--from with the Git URL to make it accessible from anywhere!
Tools Provided
run_and_screenshot
Atomic operation: Starts a QEMU VM, waits for boot, captures a screenshot, then shuts down cleanly.
This is the recommended tool for AI agents as it provides a single, deterministic step for capturing VM state.
Parameters:
Parameter | Type | Required | Description |
| string | ✅ | Architecture: |
| string | ✅ | Path to ISO or disk image to boot |
| int | ✅ | Seconds to wait before screenshot (boot time) |
| string | ❌ | Additional QEMU arguments (e.g., |
Example:
Returns: Screenshot image with metadata, or detailed error message.
capture_screenshot
Captures a screenshot of an already running QEMU instance.
Returns: A base64-encoded PNG string encased in standard image markers.
Error Handling: Provides detailed feedback if no QEMU process is found, if QMP is missing, or if the socket is unreachable.
Development & Testing
A mock server is provided in tests/mock_qmp_server.py to test the MCP server without a real QEMU instance.
Start Mock Server:
python3 tests/mock_qmp_server.pyMock QEMU Process: Rename a long-running process to
qemu-system-mockand run it with-qmp unix:/tmp/qmp-test.sock.Run MCP Client: Test the tool via your preferred MCP client or
uv run qemu-screenshot.
License
MIT
