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:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

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

winget install --id QEMU.QEMU --exact --accept-package-agreements --accept-source-agreements

3. Ensure OpenSSH Client is installed:

Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0

4. Verify:

qemu-system-x86_64 --version
qemu-img --version
ssh -V

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install -y qemu-system-x86 qemu-utils openssh-client cloud-image-utils

Linux (Fedora/RHEL family)

sudo dnf install -y qemu-system-x86 qemu-img openssh-clients cloud-utils

Linux (Arch)

sudo pacman -S --needed qemu-base qemu-desktop openssh cloud-utils

Run From GitHub URL (No Local Project Path Needed)

You can launch directly from GitHub with uvx:

uvx --from git+https://github.com/Kevin4562/QEMU-MCP.git mcp-qemu-lab

Recommended pin (branch/tag/commit):

uvx --from git+https://github.com/Kevin4562/QEMU-MCP.git@main mcp-qemu-lab

MCP Client Configuration

VSCode Codex (TOML)

Example config.toml:

Windows:

[mcp_servers.mcp-qemu-lab]
command = "uvx"
args = ["--from", "git+https://github.com/Kevin4562/QEMU-MCP.git@main", "mcp-qemu-lab"]
env = { MCP_QEMU_LAB_WORKSPACE = "C:\\Users\\User\\AppData\\Local\\mcp-qemu-lab" }

Linux:

[mcp_servers.mcp-qemu-lab]
command = "uvx"
args = ["--from", "git+https://github.com/Kevin4562/QEMU-MCP.git@main", "mcp-qemu-lab"]
env = { MCP_QEMU_LAB_WORKSPACE = "/home/user/.local/share/mcp-qemu-lab" }

Cursor (JSON)

Example mcp.json:

{
  "mcpServers": {
    "mcp-qemu-lab": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Kevin4562/QEMU-MCP.git@main",
        "mcp-qemu-lab"
      ],
      "env": {
        "MCP_QEMU_LAB_WORKSPACE": "/absolute/path/to/mcp-qemu-lab-workspace"
      }
    }
  }
}

Windows workspace example:

{
  "mcpServers": {
    "mcp-qemu-lab": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Kevin4562/QEMU-MCP.git@main",
        "mcp-qemu-lab"
      ],
      "env": {
        "MCP_QEMU_LAB_WORKSPACE": "C:\\Users\\User\\AppData\\Local\\mcp-qemu-lab"
      }
    }
  }
}

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:

uv sync
uv run --extra dev pytest -q

Integration test (real VM boot):

MCP_QEMU_LAB_RUN_INTEGRATION=1 MCP_QEMU_LAB_INTEGRATION_TIMEOUT_SEC=1800 uv run --extra dev pytest -m integration

Windows PowerShell:

$env:MCP_QEMU_LAB_RUN_INTEGRATION = "1"
$env:MCP_QEMU_LAB_INTEGRATION_TIMEOUT_SEC = "1800"
uv run --extra dev pytest -m integration

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.