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 filenames
Returns 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 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.
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.
🔍 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: PeepIt MCP
This server is designed to be used with uv for seamless execution.
Python 3.12+
uv installed (pip install uv)
A QEMU instance running with a Unix QMP socket.
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-screenshotAdd 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!
run_and_screenshotAtomic 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_screenshotCaptures 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.
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.py
Mock QEMU Process: Rename a long-running process to qemu-system-mock and 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.
MIT
Captures a screenshot of the first running QEMU instance. Prioritizes QMP (window-independent), falls back to X11 (if available).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses behavioral traits: the prioritization of QMP over X11 and the fallback mechanism. However, it doesn't cover important aspects like error handling (e.g., what happens if no QEMU instance is running), output format, or side effects. This leaves gaps in understanding the tool's behavior beyond the basic operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and well-structured: two sentences that efficiently convey the purpose and behavioral context. Every sentence adds value without redundancy, making it easy to parse and understand quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (involves QEMU and multiple capture methods), lack of annotations, and no output schema, the description is incomplete. It explains the capture process but omits details like what the output is (e.g., image format, storage location), error conditions, or dependencies. This leaves the agent with insufficient information for reliable use in varied scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so no parameters need documentation. The description doesn't add parameter semantics, which is acceptable here. A baseline of 4 is appropriate since the schema fully covers the lack of parameters, and the description doesn't need to compensate for any gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Captures a screenshot of the first running QEMU instance.' It specifies the action (captures) and target resource (screenshot of QEMU instance), though it doesn't need to distinguish from siblings since none exist. However, it could be more specific about what 'first running QEMU instance' means in ambiguous scenarios.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides implied usage context: 'Prioritizes QMP (window-independent), falls back to X11 (if available).' This suggests when certain methods are preferred, but it doesn't explicitly state when to use this tool versus alternatives (e.g., other screenshot tools) or any prerequisites. Since there are no sibling tools, the lack of explicit alternatives is less critical, but guidance on conditions for successful invocation is limited.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Generate images, GIFs, and PDFs from HTML, URLs, or templates — from your AI agent.
Screenshots, PDFs and Markdown from any URL or HTML for AI agents, via the SnapForge API
Screenshot and HTML render MCP server for AI agents
Screenshot, diff, audit and sitemap-capture any web page — 5 MCP tools for AI agents.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/veighnsche/qemu-screenshot-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
