windbg-mcp

windbg-mcp

一个 MCP 服务，可将 WinDbg/DbgEng 提供给 AI Agent （Claude Code、Claude Desktop、Cursor 等）使用——通过 stdio，或通过 --listen 使用 HTTP；后者可将相同的工具提供给不在 DbgEng 所运行机器上的客户端。它驱动实时调试器引擎，支持 用户模式、内核模式、崩溃转储和 **时间旅行调试（TTD）**工作流；还可从 Hyper-V 检查点读取 VBS 来宾的 安全内核（VTL1），或通过操作员提供的提供程序控制精确的一次性 VBS VM 中选定的 VP。

底层引擎绑定位于 dbgscope （src/dbgeng.rs）中；此 crate 在其之上添加了按会话划分的进程引擎监管，以及 rmcp 工具接口。

官方来源

本仓库 — github.com/glslang/windbg-mcp — 是 本项目唯一的官方所在地。 如果你是在其他地方阅读本文，那你看到的就是副本： 镜像可以逐字复制这份 README，因此应核对的是内容所托管的地址，而不是它声称的内容。

本项目仅通过以下渠道发布：

• 源代码：本仓库，以及用于引擎绑定的 glslang/dbgscope。
• 二进制文件：本仓库的发布页——一个 zip 和一个 .mcpb 捆绑包，二者都列在 SHA256SUMS.txt 中，并且都附有已签名的构建来源证明。
• MCP 注册表：官方注册表中的 io.github.glslang/windbg-mcp，其 io.github.glslang 命名空间只有这个 GitHub 账号能够发布内容。该条目指向上面的 .mcpb。
• Claude Code 插件：/plugin marketplace add glslang/windbg-mcp——该市场就是本仓库。

Scoop bucket由社区维护，不属于本项目；该章节说明了信任它意味着什么。

MCP 目录和市场会在未征求同意的情况下列出公开仓库。它们都与本项目无关，也不代表本项目行事，因此，在从其中使用 windbg-mcp 之前，请注意：

• 它是免费的，且没有付费版本。 它采用 MIT 许可证，没有订阅、许可证密钥或高级套餐。对它收费的列表并非本项目的发布渠道，所得款项也不会交给本项目。

• 本项目没有托管版本。 该服务会在运行它的 Windows 机器上驱动 DbgEng，调试该机器能够访问的目标，因此它应运行在你的机器上，或由你控制的机器上——--listen 是为服务你的客户端而设。将它作为服务提供的端点运行的是他人的代码，而你的 Agent 会把你正在调试的内容发送给它：转储文件、内存、跟踪记录。

• 来自其他地方的二进制文件就是你尚未审查过的调试器。 本项目运行时需要提升权限——内核附加和 TTD 录制需要管理员权限，而 --install-service 会以 LocalSystem 身份运行它——并且它会读写其他进程和内核。被篡改的构建一旦获得这些权限，就能控制整台机器以及它能访问的每个目标。从上方的发布页获取二进制文件，并在运行前进行核验：对照 SHA256SUMS.txt 检查哈希，并核验来源证明：

  gh attestation verify <file> --repo glslang/windbg-mcp `
     --signer-workflow glslang/windbg-mcp/.github/workflows/release.yml
  

文档

本文档是索引。每个主题对应一份文档，每份文档涵盖该主题的全部内容。

安装和引擎设置	依赖项、预构建二进制文件、Scoop，以及一次性复制 WinDbg 引擎的操作；TTD 回放、!analyze、驱动工具和 32 位 .NET SOS 都需要此操作
与 MCP 客户端搭配使用	客户端配置、在另一台机器上运行服务（--listen）、两个 Claude Code 插件（服务本身，以及绘制其调用的 WinDbg 窗格）、MCP 注册表
架构	为什么采用一个监督进程和每个会话一个引擎工作进程、各源文件的职责，以及所提供的 MCP 修订版本
工具概览	如何通过 --tools 提供更少的工具、类型化操作数可能包含的内容，以及控制流和 TTD 工具的行为
会话和会话句柄	session_id 路由、四个会话的上限、interrupt、进度通知，以及恢复已暂停的附加操作
内核连接配置文件	将 KDNET 调试密钥排除在工具参数和客户端记录之外
虚拟机监控程序调试	通过 KDNET 附加到 Microsoft 虚拟机监控程序，包括目标标识、限制和单独的实时测试
安全内核研究	转储检查、实时 VTL1 读取、已初始化内核的停止/单步结果，以及操作员提供程序控制契约
结构化结果	哪些工具通过 structuredContent 返回结果、每项内容包含什么，以及调用方可据此分支处理的错误类别
事务批处理	debug_batch：无论目标路径如何（包括超时或断开连接），都会运行清理操作的变更序列
遍历结构	walk_memory：列表、数组和链；无法读取的节点会作为一行显示，而不会终止遍历
会话记录	WINDBG_MCP_TRANSCRIPT：记录每次调用的 JSONL 文件、脱敏内容，以及如何将其渲染为 asciicast
限制和说明	需要如实说明的限制——TTD 仅支持用户模式，静态可达性分析仅尽力而为，池遍历需要已停止的 x64 内核，堆遍历需要已停止的 x64 或 ARM64 进程
操作指南	端到端的完整操作流程：崩溃转储分诊、TTD、Flare-On 解题、驱动 IOCTL 接口
本地模型评测	模型 × 工具范围 × 上下文窗口的网格，与经过验证的答案集进行对照：笔记本大小的模型能驱动哪些操作，以及它发现的本服务中的两个缺陷

操作员和参考资料：远程侦听器、 使用 ollama 驱动、 使用 Apple 设备端模型驱动、 反汇编器坐标、 冒烟测试、令牌预算、 发布。 安全内核（VTL1）有五条路径。选择加入的 securekernel 组包含用于固定捕获的四个工具、用于选定 VP 实时控制的十一个工具、受管 KD 门面、用于在普通内核会话中跟踪 VTL0 安全服务入口的两个工具，以及用于独立虚拟机监控程序转换跟踪的两个工具；会话约定见 docs/sessions.md。单独的 --sk-live 命令行角色可解码正在运行的来宾，但不会控制它；--sk-kd-target 角色则会在本地命名管道上，将已安装的 WinDbg 接入实时控制会话，具体限制见 docs/secure-kernel/kd-facade.md。实时解码、实时控制和门面都需要由操作员提供本仓库未附带的传输方式。VTL0 跟踪和来宾测试框架的文档见 docs/secure-kernel/vtl0-call-trace.md；中间的虚拟机监控程序跟踪见 docs/secure-kernel/hypervisor-transition-trace.md。证据、控制措施和无效尝试已 逐个关卡记录。

快速开始

Windows x64，使用来自 System32 的 dbgeng.dll——足以进行实时用户模式、内核和崩溃转储工作。TTD .run 回放、!analyze 和驱动程序工具各自需要引擎未附带的文件；一次性复制请参阅docs/install.md。

从发行版下载预构建的 windbg-mcp-vX.Y.Z-windows-x64.zip，或自行构建：

cargo build --release

然后让客户端连接到该二进制文件：

// .mcp.json  (or claude_desktop_config.json under "mcpServers")
{
  "mcpServers": {
    "windbg": {
      "command": "C:\\workspace\\windbg-mcp\\target\\release\\windbg-mcp.exe"
    }
  }
}

客户端和模型无需运行在 DbgEng 所在的位置：--listen <addr> 会通过 HTTP 提供相同的工具，每个客户端使用一个 bearer 令牌，因此 Mac 可以控制 Windows VM——模型本身也可以是本地模型。下文的驱动方式——托管或本地，在此处或另一台机器上介绍了相关配置。

cargo test 会运行单元测试以及通过 stdio 驱动已构建二进制文件的端到端冒烟测试；依赖项升级或 MCP 规范修订后请运行它——参见docs/smoke-test.md。

工作原理

每个进程只有一个调试会话。 dbgeng.dll 在每个进程中只持有一个被调试对象会话，因此此服务会在一个监督进程中运行 MCP 协议，并将每个打开的目标放在各自的引擎工作进程子进程中。这会带来两点影响：无法收尾的会话——例如等待来宾始终不发起连接的实时内核附加——消耗的是一个进程，而不是整个服务；会话也可以并发运行（例如在实时内核附加期间排查崩溃转储，最多同时四个）。

每个访问目标的工具都会接收打开目标时返回的 session_id，并据此路由调用。省略它时，调用会发往当前会话。docs/architecture.md介绍了进程模型和逐文件说明；docs/sessions.md介绍了句柄规则、数量上限以及会话卡住时的处理方法。

**32 位目标使用 32 位工作进程。**扩展 DLL 会加载到调试器自己的进程中，因此要访问 32 位目标上的 .NET SOS，只能使用 32 位主机——进程加载映像后无法再变成 32 位。因此，发行版还会在 x86\windbg-mcp.exe 中附带此服务的第二个构建版本；打开 32 位转储或 WoW64 attach_process 时，会由该工作进程处理，而不是重新运行 x64 版本。客户端无法察觉差异：仍是一个服务、一个句柄、一套工具界面。如果缺少该工作进程或其 32 位引擎，目标仍可由 x64 构建版本打开——对其进行原生分析一直可行——并会在打开器的 limitation 中说明这一点。

工具

九个 --tools 组中共有 89 个工具；下表会按主题拆分其中部分组。--tools 列中的名称用于选择工具组——参见提供较少的工具。

分组	--tools	工具
会话	session	open_dump、open_trace、attach_kernel_local、attach_kernel、attach_process、launch、interrupt、end_session、session_status
服务端	session	server_log — 服务端自身的日志：主管程序的记录，以及你打开的会话的记录，并标明每条记录所属的会话
状态	inspect	current_location（指令指针、执行上下文和 PE 坐标）、registers、read_memory、backtrace（以类型化帧表示的堆栈；每帧都带有符号，以及引擎能够定位时提供的 module+RVA）、modules（refresh: true 会先将调试器清单与目标重新同步 — 新内核连接需要此步骤，才能判断“未加载”是否有意义）、threads、disassemble（以记录形式表示的指令；每条记录都包含其编码，以及引擎能够定位时提供的 RVA）、dx、set_symbol_path
崩溃	crash	crash_triage — 将错误检查码表示为字段：代码和参数、崩溃进程、以 module+RVA 表示的堆栈，以及故障驱动程序帧；exception_triage — 用户模式下的对应工具：解码后的异常记录、故障类型、抛出的 C++ 对象及其携带的 HRESULT，以及从崩溃上下文遍历出的堆栈；decode_error_reporting — 将 HRESULT、NTSTATUS 或 Win32 错误表示为字段，并附上系统自身表格给出的消息
控制	exec	go、step_over、step_into、set_breakpoint、breakpoints（会话的完整清单，以记录形式呈现 — 在恢复或分离仍在运行的目标前可检查）、clear_breakpoints（按 ids 清除，或使用 all: true）、run_to_address
异步控制	exec	continue_async（恢复运行并返回句柄）、wait_for_stop（收集停止事件；等待超时属于轮询，不是失败）、break_in
事务	batch	debug_batch — 按顺序执行的操作序列，包含断言和回滚；只要引擎进程仍能识别其将要操作的目标，就会在所有执行路径上运行回滚
TTD 导航	ttd	step_back（t-）、step_over_back（p-）、reverse_go（g-）、goto_position（!tt）
TTD 分析	ttd	ttd_calls、ttd_memory、ttd_events、index_trace、record_trace
驱动程序 IOCTL	ioctl	decode_ioctl、driver_object、device_object、irp_stack、ioctl_trace、reachable_from_dispatch、driver_hazards、ioctl_map — 从分派例程自身代码中恢复并解码其接受的控制代码；xrefs_to — 从已解码的控制流中读取映像内哪些位置会调用或跳转到某个地址，并为每个位置提供模块+RVA 和节；device_security — 谁可以打开设备：以主体和访问掩码表示的安全描述符、FILE_DEVICE_SECURE_OPEN，以及可访问该设备的符号链接；driver_surface — 一次调用检查一个驱动程序：其分派表、带有各自访问门控的设备（不含符号链接）、ioctl_map 的结果和 driver_hazards 的结果；每个部分都会报告自身状态
内核池	allocator	pool_find_tag、pool_chunk、pool_census、pool_diagnostics；pool_trace — 在内核运行期间记录单个驱动程序的池分配；通过在该驱动程序自身的调用位置设置断点，不会因分配器的其他调用者而暂停目标；pool_trace_read — 读取记录内容：大小、标记、标志或池类型、返回的地址和线程
用户堆 Segment Heap	allocator	heap_list、heap_allocations、heap_chunk、heap_census、heap_diagnostics
结构遍历	allocator	walk_memory
原始	inspect	execute — 运行任意调试器命令，并返回完整文本输出
安全内核（额外）	securekernel	捕获：open_sk_capture、sk_modules、sk_read_memory、sk_symbol。实时选定 VP 控制：open_sk_live_control、sk_live_arm、sk_live_wait、sk_live_break、sk_live_registers、sk_live_read_memory、sk_live_write_memory、sk_live_step、sk_live_continue_to_breakpoints、sk_live_continue_to_software_breakpoints、sk_live_continue，以及由清单固定的 sk_service_trace / sk_service_trace_read 生命周期、托管的 open_sk_kd 门面和单句柄 open_sk_debugger 组合工具。在普通内核会话中进行 VTL0 调用跟踪：sk_call_trace、sk_call_trace_read。在独立的虚拟机监控程序 KD 会话中跟踪虚拟机监控程序转换：hv_transition_trace、hv_transition_trace_read。实时会话可以通过独立验证的提供程序额外启用选定 VP。默认不包含此额外分组；请指定其名称，或使用 --tools all。捕获需要已获准的 Windows SDK 保存状态提供程序根目录；实时控制需要启动策略、操作员提供的特权提供程序以及精确匹配构建版本的 vmwp 配置文件。写入和软件断点还需要明确的启动策略授权，以及有界且指令一致的传输能力；首个软件断点切片和语义跟踪器需要已证实只有一个 vCPU 的 Hyper-V 虚拟机。
默认提供普通的 8 个组；securekernel 扩展为可选。显式设置 --tools all 会提供全部 89 个工具。--tools session,inspect,crash 会将工具范围缩减到 23 个，而 --listen 客户端可使用与运行默认设置不同的工具范围。此处不再重复具体字节数：这些数据列在 docs/tool-surface.md 的表格中，every_documented_surface_figure_matches_the_served_surface 会将其与运行中的服务进行核对；而此前写在这句话里的数值，在数据一天内变动两次后就过时了。该页面还列出了计算方法、session 始终包含在内的规则，以及类型化操作数不得包含的内容。

大多数工具还会通过 MCP structuredContent 返回结果，因此程序可以直接读取字段，而不必解析文字；失败时也会返回稳定的类别（invalid_argument、debugger、timeout、stale_session 等），而非依赖具体措辞 — docs/structured-results.md。

演练

包含实际输出和注意事项的完整操作示例 — 长篇版本见 docs/walkthroughs.md。

• 崩溃转储排查 — 追踪由 nvlddmkm.sys 引起的 0x9F DRIVER_POWER_STATE_FAILURE，以及发生在没有 PDB 的驱动程序中的 0x13A。
• TTD 巡览 — 打开 .run，进行正向／反向导航，并使用符号统计 printf 调用次数。
• Flare-On 12 #8 — 对一个混淆过的 Qt crackme 进行完整的 TTD → Z3 求解。
• 驱动程序 IOCTL 范围 — 在运行中的 KDNET 内核上还原分派 switch，并判断用户模式下的可达性。
• Explorer 无法启动 — 服务调试自身宿主：追踪一个失效的 Windows Shell，经过三次故障定位到格式错误的 State Repository。
• 他人组件中的崩溃 — 一个 Windows SDK DLL 因 GSL 合约违规而崩溃，并将其整理成报告：一份 12 行的复现代码、用于隔离触发条件的对照矩阵，以及报告明确拒绝声称的内容。
• 反汇编器坐标 — 将 crash_triage 堆栈帧与另一台计算机上获取的映像中的函数对应起来。

驱动方式——托管运行或本地运行，在本机或另一台机器上

任何支持 MCP 的程序都可以承载此服务，只有 DbgEng 被限定在 Windows 上。 因此，模型可以是在编辑器中运行的托管模型、ollama 中的本地模型，或 ollama 云端模型， 而且不必运行在被调试的机器上。

驱动方	运行位置	服务	通过何种方式访问
MCP 客户端 — Claude Code、Cursor、Claude Desktop	Windows 机器	由客户端启动	stdio
MCP 客户端	Mac 或任何其他机器	Windows 主机，通过 --listen 运行，通常作为服务	通过 ssh 转发的 HTTP
ollama 中的模型	Windows 机器	同一台机器，通过 --listen 在 loopback 上运行	loopback 上的 HTTP
ollama 中的模型	Mac	Windows 主机，通过 --listen 作为服务运行	通过 ssh 转发的 HTTP
ollama 云端模型	ollama 运行的位置	上述任一方式	无变化——只有标签不同

单台机器无需任何配置：客户端会启动二进制文件，并通过 stdio 与其通信，这就是上面的快速开始。

两台机器需要监听器。 对于你本来就要驱动的会话，在 Windows 主机上以前台方式运行——无论二进制文件位于何处，这种方式都可行：

$env:WINDBG_MCP_LISTEN_TOKEN = "<a long random string>"   # this shell only
windbg-mcp.exe --listen 127.0.0.1:8765

对于任何需要长期运行的情况，都应从受保护的目录将其安装为服务。 SCM 会将确切路径存储为 LocalSystem 自动启动服务，因此，任何能够写入该目录或将引擎 DLL 放到 exe 旁边的人，都能在下次启动时以 SYSTEM 身份运行代码。 因此，--install-service 会拒绝将 exe 安装在 %ProgramFiles%、%ProgramFiles(x86)% 或 %SystemRoot% 以外的位置——下载的 zip、Scoop shim 或 target\release 构建都属于这种情况——所以请先移动整个部署：exe、放在其旁边的引擎 DLL，以及 x86\。然后，以提升的权限运行：

$env:WINDBG_MCP_LISTEN_TOKEN = "<a long random string>"   # this shell only
& "$env:ProgramFiles\windbg-mcp\windbg-mcp.exe" --install-service --listen 127.0.0.1:8765
Start-Service windbg-mcp          # --install-service only *registers* it

如果机器完全归你所有，--allow-unprotected-path 会明确表明这一点并在原位置安装；这是开发安装，而非部署。

无论采用哪种方式，都可以在你实际工作的机器上，按需保持连接：

ssh -N -L 8765:127.0.0.1:8765 <windows-host>

监听器没有令牌就会拒绝启动，因为它提供 execute、launch 和 debug_batch——在这里开放端口，意味着任何人都能在持有内核调试器的主机上执行任意代码。 请绑定到 loopback 并通过 ssh 转发，而不是将其暴露出去。每个客户端都以自身身份进行身份验证，并且可以获得比运行默认配置更精简的 --tools 工具集，这样本地模型和编辑器就能共享一个监听器，而无需共享会话。 docs/remote-listener.md 是供运维人员参考的文档。

让 ollama 连接到它是客户端的职责，而非此服务的职责。 驱动 ollama 模型的 MCP 客户端会像编辑器一样承载监听器——这里无需安装任何内容，此服务也永远不会得知响应的是哪种模型。ollama 为其中许多客户端提供集成；运行 ollama launch 可列出这些集成，ollama launch claude --model <tag> 就是其中一种。本地标签和 ollama 云端标签使用相同的路径，只有模型名称不同。

docs/local-model.md 是运行手册：各种配置方式、如何选择能够实际运行的模型、安静的模型会因两个时钟中的哪一个而丢失会话，以及云端标签无法再告诉你有关其自身运行的哪些信息。

本地模型能否胜任——基准测试

每轮都会消耗工具调用额度，因此，“在笔记本电脑上运行的模型能否真正驱动这个服务？” 这个问题既关乎模型，也关乎本服务。仓库提供的是基准测试，而非断言：tools/local_model_eval.py 会针对模型 × 工具面 × 上下文窗口运行网格测试；tools/bench_listener.ps1 会通过一个监听器提供全部三种工具面，并将它们作为三个分别分配预算的客户端；答案则是在任何模型查看转储文件之前，先用本服务自带的工具读取已提交到仓库的崩溃转储得出的。Claude 在网格中充当对照组，而非竞争者。docs/local-model-eval.md 是详细说明。

要亲自运行网格测试，需要的是开发环境，而非发布包：发布包包含 windbg-mcp.exe、x86\ 工作器和 LICENSE，因此 tools/ 需要从代码库检出；驱动程序和评分程序则使用 Python 3。本节之前的所有内容都不需要这些——用本地模型驱动服务是客户端的工作，而此处的驱动程序仅用于逐个任务列表地测量效果，不提供交互模式。 agent-sandbox-vm 是本项目开发和基准测试所用的 Hyper-V / Parallels 虚拟机环境。

• 上下文窗口并非限制因素——但这只适用于该基准测试所用的运行时，这一点很重要。一个包含 17,300 个 token 的工具面，在实际提供 8,192 个 token 窗口的情况下，回答了全部六项任务，其中也包括多轮任务中携带的 10,000 个字符的工具输出。预测结果会不同的那套计算见 docs/local-model.md，但它错了；不要把任一结果一概而论，直接运行 ollama ps 查看你自己的运行时实际提供了多少。
• 将 51 个工具缩减到 11 个，会让六个答案中有两个无法给出——这是网格测量的工具面，还未包含三个异步执行工具。这里的大多数事实都能通过多种途径获取，因此精简工具面只保留关键工具。
• 它测量的是本服务，而后才是模型。 首轮网格记录的所有工具面外调用，所用名称都是本服务曾公布、随后却拒绝的工具名称——这些名称既出现在连接时发送的 instructions 中，也出现在本服务实际提供的工具描述中。现在，这两处内容都会按客户端分别缩减；重新运行精简工具面测试后，这类调用从 17 次降至 6 次，而由服务告知的名称调用数降至零。

工具面网格 是可视化的详细说明——包含 33 个单元、五个模型、三个维度，以及由此产生的两项修复各自带来了什么、又未能带来什么。

局限性

完整列表及每项局限对工作流的影响，见 docs/limitations.md。最容易让人遇到的四项：

• TTD 仅支持用户模式——这是 Microsoft 的限制，因此无法对内核目标进行时间旅行调试。
• 每个会话一次只能执行一条命令。 会话可以并发运行，但每个会话都由一个引擎串行执行操作：必须先等待每次调用的结果，再向该会话发送下一次调用。
• 符号名称需要在调试器主机上进行设置——需要在二进制文件旁放置 msdia140.dll、设置符号路径，并且（使用 TTD 时）在已停止的位置重新加载符号。未完成这些设置时，仍可执行基于地址的查询。
• 池遍历器需要已停止的 x64 内核，堆遍历器则需要已停止的 x64 或 ARM64 进程。 无论由哪个工作器持有，32 位或 WoW64 进程都没有 heap_* 工具，因为其堆采用 32 位结构——SOS 自带的 !dumpheap/!eeheap 是托管环境下的等效工具；32 位工作器及其 x86\ 引擎负载 (docs/install.md) 正是为了访问这些工具。