QEMU MCP

mcp qemu实验室

用于QEMU客户机中Linux二进制分析的本地模型上下文协议（MCP）服务器。

此服务器通过STDIO运行，默认情况下是安全的，并公开了以下工具：

• VM生命周期（创建/启动/停止/快照）
• 完整的客户机RAM转储
• 访客调试器工作流和每个进程的核心转储
• 工件索引/资源（工具输出中的元数据，通过MCP资源的文件内容）

仓库的规划

• mcp_qemu_lab/ 服务器源
• tests/ 单元/集成测试
• pyproject.toml 包裹+入口点
• uv.lock 固定Python依赖锁定文件

未在git中跟踪：

• 运行时工作区/日志/工件(.mcp-qemu-lab*/)
• 本地虚拟envs(.venv/)
• 本地工具缓存(tools/)
• 本地示例二进制文件(test samples/)

主机要求

• Python 3.11+
• uv 包管理器
• QEMU(qemu-system-x86_64 和 qemu-img)
• OpenSSH客户端工具(ssh, scp, ssh-keygen)

安装主机依赖关系

视窗

1. 安装 uv:

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

1. 安装QEMU（包括 qemu-system-x86_64.exe 和 qemu-img.exe):

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

1. 确保已安装OpenSSH客户端：

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

1. 验证：

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家族）

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

从GitHub URL运行（不需要本地项目路径）

您可以直接从GitHub启动 uvx:

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

推荐引脚（分支/标签/提交）：

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

MCP客户端配置

VSCode法典（TOML）

示例 config.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：

[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" }

游标（JSON）

示例 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工作区示例：

{
  "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"
      }
    }
  }
}

安全默认值

• 访客网络默认值： net_mode="none"
• 默认情况下没有主机目录共享
• guest_exec 除非 unsafe_allow_arbitrary_commands=true 每次通话
• 工具输出仅返回JSON元数据（无原始内存字节）
• 工件存储在磁盘上，并通过MCP资源公开
• 每次工具调用都会写入审计JSONL条目

关键工具

• 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

资源

• artifact://{artifact_id} 人工制品内容
• artifact-index://all 工件元数据索引

开发设置（可选的本地克隆工作流）

如果您正在本地开发此仓库：

uv sync
uv run --extra dev pytest -q

集成测试（真实VM引导）：

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

故障排除

• dependency_missing：安装QEMU/OSSH并验证二进制文件是否已打开 PATH.
• dependency_privilege_required：使用提升的权限重新运行安装命令。
• ssh_unavailable：VM必须使用创建 net_mode="user" 基于SSH的工具。
• gdb/连接失败：运行 guest_wait_ready(..., require_gdb=true) 在调试器/核心工具之前。