mcp-qemu-lab

Local Model Context Protocol (MCP) server for Linux binary analysis in QEMU guests.

This server runs over STDIO, is safe by default, and exposes tools for:

• VM lifecycle (create/start/stop/snapshots)

• Full guest RAM dumps

• In-guest debugger workflows and per-process core dumps

• Artifact indexing/resources (metadata in tool output, file content via MCP resources)

Repository Layout

• mcp_qemu_lab/ server source

• tests/ unit/integration tests

• pyproject.toml package + entrypoint

• uv.lock pinned Python dependency lock file

Not tracked in git:

• runtime workspaces/logs/artifacts (.mcp-qemu-lab*/)

• local virtual envs (.venv/)

• local tool caches (tools/)

• local sample binaries (test samples/)

Host Requirements

• Python 3.11+

• uv package manager

• QEMU (qemu-system-x86_64 and qemu-img)

• OpenSSH client tools (ssh, scp, ssh-keygen)

Install Host Dependencies

Windows

1. Install uv:

2. Install QEMU (includes qemu-system-x86_64.exe and qemu-img.exe):

3. Ensure OpenSSH Client is installed:

4. Verify:

Linux (Ubuntu/Debian)

Linux (Fedora/RHEL family)

Linux (Arch)

Run From GitHub URL (No Local Project Path Needed)

You can launch directly from GitHub with uvx:

Recommended pin (branch/tag/commit):

MCP Client Configuration

VSCode Codex (TOML)

Example config.toml:

Windows:

Linux:

Cursor (JSON)

Example mcp.json:

Windows workspace example:

Safety Defaults

• Guest networking default: net_mode="none"

• No host directory sharing by default

• guest_exec allowlist unless unsafe_allow_arbitrary_commands=true per call

• Tool outputs return JSON metadata only (no raw memory bytes)

• Artifacts are stored on disk and exposed via MCP resources

• Every tool call writes audit JSONL entries

Key Tools

• ensure_dependencies

• vm_create, vm_start, vm_status, vm_stop

• vm_snapshot_save, vm_snapshot_load

• guest_wait_ready

• guest_exec, guest_copy_in, guest_copy_out

• process_list, process_maps

• debugger_attach, debugger_set_breakpoint, debugger_continue, debugger_read_registers, debugger_detach

• process_dump_core

• guest_dump_memory

• artifacts_list

• vm_logs_tail

Resources

• artifact://{artifact_id} artifact content

• artifact-index://all artifact metadata index

Development Setup (Optional Local Clone Workflow)

If you are developing this repo locally:

Integration test (real VM boot):

Windows PowerShell:

Troubleshooting

• dependency_missing: install QEMU/OpenSSH and verify binaries are on PATH.

• dependency_privilege_required: rerun install command with elevated permissions.

• ssh_unavailable: VM must be created with net_mode="user" for SSH-based tools.

• gdb/attach failures: run guest_wait_ready(..., require_gdb=true) before debugger/core tools.