AI导哈

QEMU虚拟机二进制分析服务器

一个基于QEMU的本地模型上下文协议(MCP)服务器，用于Linux二进制分析，提供虚拟机生命周期管理、内存转储和调试工具。

  • by Kevin4562
  • Python
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 Kevin4562/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) 在调试器/核心工具之前。

相关 MCP