QEMU Screenshot MCP Server
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 "Deploy 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 Server capture 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.
Related MCP server: mcp-incus-vm
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:
qemu-system-x86_64 ... -qmp unix:/tmp/qmp-socket,server,nowait# To run from your local directory:
uvx --from /home/vince/Projects/qemu-screenshot-mcp qemu-screenshot
# To run from a GitHub repository (after you push it):
uvx --from git+https://github.com/veighnsche/qemu-screenshot-mcp.git qemu-screenshotConfiguration in Claude Desktop (or other MCP clients)
Add the following to your MCP configuration file (e.g., config.json for Claude Desktop):
{
"mcpServers": {
"qemu-screenshot": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/veighnsche/qemu-screenshot-mcp.git",
"qemu-screenshot"
]
}
}
}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:
{
"arch": "x86_64",
"image": "/path/to/archlinux.iso",
"screenshot_delay_seconds": 10,
"extra_args": "-m 4G -enable-kvm"
}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
Available Tools
1 toolcapture_screenshotA
Captures a screenshot of the first running QEMU instance. Prioritizes QMP (window-independent), falls back to X11 (if available).
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 1 tool
With only one tool, there is no possibility of ambiguity or overlap between tools. The single tool has a clear and distinct purpose of capturing screenshots from QEMU instances.
With only one tool, naming consistency is inherently perfect. The tool name 'capture_screenshot' follows a clear verb_noun pattern and sets a consistent standard, though there are no other tools to compare it against.
A single tool is too few for most server purposes, as it severely limits functionality and scope. While it may be appropriate for a minimal utility, it feels thin and incomplete for a server named 'QEMU Screenshot MCP Server', which suggests broader screenshot-related capabilities.
The tool surface is severely incomplete for a screenshot server. It only captures screenshots from the first running QEMU instance, with no tools for listing instances, selecting specific ones, managing captures, or handling errors, leading to significant gaps that will cause agent failures.
Related MCP Connectors
Generate images, GIFs, videos, and PDFs from HTML, URLs, or templates β from your AI agent.
Screenshot API for AI agents. Any public page as image or PDF, banners hidden, 227 countries.
Screenshot, PDF and Open Graph image API for AI agents: capture pages, render PDFs, make OG images.
Screenshot any public web page from an AI agent. Free without signup, or with an API key.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI agents to capture and analyze screenshots of macOS applications, windows, or the entire screen using local (Ollama) or cloud-based AI vision models, with non-intrusive, fast screen capture via Apple's ScreenCaptureKit.323 npm2MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to control and automate Incus/QEMU virtual machines via SSH, supporting mouse/keyboard, screenshots, commands, and lifecycle management.MIT
- FlicenseAqualityDmaintenanceProvides agents with temporary visual capture of Hyprland/Wayland monitors, windows, or regions as PNGs, enabling visual verification and self-correction of UI and desktop tasks.8-
- 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