Skip to main content
Glama
QEMU Screenshot MCP Server

QEMU Screenshot MCP Server

by veighnsche

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+

  • uv installed (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-screenshot

Configuration 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"
      ]
    }
  }
}
TIP

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

arch

string

βœ…

Architecture: "x86_64" or "aarch64"

image

string

βœ…

Path to ISO or disk image to boot

screenshot_delay_seconds

int

βœ…

Seconds to wait before screenshot (boot time)

extra_args

string

❌

Additional QEMU arguments (e.g., "-m 2G -smp 2")

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.

  1. Start Mock Server: python3 tests/mock_qmp_server.py

  2. Mock QEMU Process: Rename a long-running process to qemu-system-mock and run it with -qmp unix:/tmp/qmp-test.sock.

  3. Run MCP Client: Test the tool via your preferred MCP client or uv run qemu-screenshot.

License

MIT

Available Tools

1 tool
capture_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

    A3.6/5.0

    Scored across 1 tool

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count2/5

    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.

    Completeness2/5

    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

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables 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.
      3
      23 npm
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to control and automate Incus/QEMU virtual machines via SSH, supporting mouse/keyboard, screenshots, commands, and lifecycle management.
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Nido 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.
      6
      2
      MIT