QEMU Screenshot

You can use this MCP server to interact with running QEMU instances and capture high-quality screenshots via the QEMU Machine Protocol (QMP). Screenshots are saved with timestamps for easy access and can be retrieved as base64-encoded PNGs along with useful metadata.

How to use

You have two main ways to obtain a screenshot through an MCP client. First, start a new QEMU VM and let the server capture a screenshot after the VM boots. This is an atomic operation that starts the VM, waits for it to boot, captures the screenshot, and then shuts the VM down cleanly. Second, capture a screenshot from an already running QEMU instance by targeting its QMP socket. In both cases you receive a PNG image along with metadata such as the absolute file path and filename, or a base64-encoded PNG you can embed directly in interfaces.

How to install

Prerequisites you need before running the MCP server are clear __and non-negotiable__.

Install Python 3.12 or newer and the uv tool which runs MCP servers efficiently.

Install uvx for running MCP servers from a repository or local path.

Ensure a QEMU instance is running with a Unix QMP socket exposed, so the MCP server can connect and capture screenshots.

Below are concrete commands you can run to set up and start the MCP server using a Git URL for the MCP package.

Configuration and usage notes

To run the MCP server from a repository, you can execute the following from any working directory where you want to host the server. This uses uvx to fetch the MCP package directly from the Git URL and start the server named qemu-screenshot.

Run the server locally from your environment with the Git-based source:

Security and maintenance notes

Keep your QMP socket secure because it provides control over the VM. Use file-system permissions and, if possible, restrict access to the host machine or container environment. Regularly update both QEMU and the MCP package to benefit from security patches and new features.

Troubleshooting and tips

If you encounter issues finding a QEMU process, verify that there is an active VM with a Unix QMP socket and that the socket path is accessible to the MCP server. If the server cannot connect to QMP, check socket permissions and QMP server configuration in QEMU’s startup arguments.

Examples and practical workflows

Atomic workflow example: start a VM, wait for boot, capture a screenshot, then shut down the VM. You receive a PNG with metadata. This is ideal for AI workflows that need deterministic VM state snapshots.

What you can do with the provided tools

run_and_screenshot: Start a QEMU VM, wait for boot, capture a screenshot, and shut down the VM cleanly. This is the recommended tool for AI agents to obtain a single, deterministic snapshot of VM state.

capture_screenshot: Capture a screenshot of an already running QEMU instance. Returns a base64-encoded PNG string and provides detailed error information if the QMP socket is missing or unreachable.

Code and configuration samples

{
  "mcpServers": {
    "qemu_screenshot": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/veighnsche/qemu-screenshot-mcp.git",
        "qemu-screenshot"
      ]
    }
  }
}

Available tools

run_and_screenshot

Atomic operation that starts a QEMU VM, waits for boot, captures a screenshot, and then shuts down cleanly. This provides a deterministic single-step snapshot for AI agents.

capture_screenshot

Captures a screenshot from an already running QEMU instance and returns a base64-encoded PNG with detailed error information if issues occur.