# 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+
- `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:
```bash
qemu-system-x86_64 ... -qmp unix:/tmp/qmp-socket,server,nowait
```
```bash
# 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):
```json
{
"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:**
```json
{
"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
