# 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
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`):
```powershell
winget install --id QEMU.QEMU --exact --accept-package-agreements --accept-source-agreements
```
3. Ensure OpenSSH Client is installed:
```powershell
Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0
```
4. Verify:
```powershell
qemu-system-x86_64 --version
qemu-img --version
ssh -V
```
### Linux (Ubuntu/Debian)
```bash
sudo apt update
sudo apt install -y qemu-system-x86 qemu-utils openssh-client cloud-image-utils
```
### Linux (Fedora/RHEL family)
```bash
sudo dnf install -y qemu-system-x86 qemu-img openssh-clients cloud-utils
```
### Linux (Arch)
```bash
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`:
```bash
uvx --from git+https://github.com/Kevin4562/QEMU-MCP.git mcp-qemu-lab
```
Recommended pin (branch/tag/commit):
```bash
uvx --from git+https://github.com/Kevin4562/QEMU-MCP.git@main mcp-qemu-lab
```
## MCP Client Configuration
### VSCode Codex (TOML)
Example `config.toml`:
Windows:
```toml
[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:
```toml
[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`:
```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:
```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": "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:
```bash
uv sync
uv run --extra dev pytest -q
```
Integration test (real VM boot):
```bash
MCP_QEMU_LAB_RUN_INTEGRATION=1 MCP_QEMU_LAB_INTEGRATION_TIMEOUT_SEC=1800 uv run --extra dev pytest -m integration
```
Windows PowerShell:
```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.
