# 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.