WinDbg MCP

一个 MCP（模型上下文协议）服务器，将 pybag 的每一个 Windows 调试器功能暴露为原生 MCP 工具。它允许任何兼容 MCP 的客户端（Claude Desktop、Claude Code、Cowork、OpenAI Codex CLI、Cursor 以及自定义代理）全面控制用户态进程、内核会话和崩溃转储分析——全部通过类型化工具调用和结构化 JSON 响应完成。

系统要求

• 仅限 Windows — pybag 需要 Microsoft Debugging Tools for Windows
• Python 3.10+
• Microsoft Debugging Tools for Windows（Windows SDK 的一部分）

安装

1. 克隆仓库```bat

git clone https://github.com/your-username/windbg-mcp.git cd windbg-mcp

### 2. 安装 Python 依赖```bat
pip install pybag mcp

3. 安装 Microsoft 调试工具

下载 Windows SDK，并在安装过程中选择 Debugging Tools for Windows： https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/

连接到 LLM IDE 和客户端

服务器作为本地 stdio 进程运行。以下所有客户端都以相同方式启动它—— python <path-to>/windbg_mcp.py——但每个客户端有自己的配置格式。

Claude Desktop

编辑 Claude Desktop 配置文件并添加 windbg-mcp 条目：

配置文件位置：

• Windows：%APPDATA%\Claude\claude_desktop_config.json
• macOS：`~/Library/Application Support/Claude/claude_desktop_config.json````json { "mcpServers": { "windbg-mcp": { "command": "python", "args": ["C:\path\to\windbg-mcp\windbg_mcp.py"] } } }

重启 Claude Desktop。所有 55 个调试工具将自动显示。

---

### Claude Code（命令行界面）

运行以下命令一次以注册服务器。Claude Code 将条目存储在其自己的 MCP 配置中，并在每次后续会话中使这些工具可用。```bash
claude mcp add windbg-mcp python C:\path\to\windbg-mcp\windbg_mcp.py

要验证服务器已注册：```bash claude mcp list

稍后删除：```bash
claude mcp remove windbg-mcp

Claude Cowork

有两种方式可将 WinDbg MCP 添加到 Cowork：通过 JSON 配置（快速）或 安装为 .mcpb 插件包（可移植、可共享）。

选项 A — JSON 配置

1. 打开 Claude 桌面应用，进入 设置 → MCP 服务器。
2. 点击 添加服务器，粘贴以下内容：```json { "windbg-mcp": { "command": "python", "args": ["C:\path\to\windbg-mcp\windbg_mcp.py"] } }

3. 保存并重启 Cowork。这些工具将在您下次会话中可用。

#### Option B — 安装为 `.mcpb` 插件包

`.mcpb` 文件是插件目录的压缩包，Cowork 可以直接安装。这是在团队间或跨机器分享服务器时的推荐方式。

**步骤 1 — 构建 `.mcpb` 文件**

从克隆仓库的根目录运行：```bat
powershell -Command "Compress-Archive -Path '.\*' -DestinationPath 'windbg-mcp.zip'; Rename-Item 'windbg-mcp.zip' 'windbg-mcp.mcpb'"

这会创建 windbg-mcp.mcpb 到当前目录，打包了 windbg_mcp.py、manifest.json 以及其他项目文件。

步骤 2 — 在 Cowork 中安装

1. 打开 Claude 桌面应用。
2. 前往 设置 → 插件（或 扩展）。
3. 点击 安装插件 并选择 windbg-mcp.mcpb。
4. Cowork 会读取捆绑包中的 manifest.json，注册 MCP 服务器，然后所有工具即可立即使用 —— 无需手动配置路径。

本仓库中捆绑的 manifest.json 已正确配置：```json { "manifest_version": "0.2", "name": "windbg-mcp", "version": "1.0.0", "description": "WinDbg MCP — full Windows debugger control via MCP tools", "server": { "type": "python", "entry_point": "windbg_mcp.py", "mcp_config": { "command": "python", "args": ["${__dirname}/windbg_mcp.py"] } } }

`${__dirname}` 在安装时解析为 Cowork 解压包的目录，因此您无需硬编码任何路径。

---

### OpenAI Codex CLI

将服务器添加到您的 Codex CLI 配置文件中。该文件通常位于 `~/.codex/config.json`（Linux/macOS）或 `%USERPROFILE%\.codex\config.json`（Windows）。```json
{
  "mcpServers": {
    "windbg-mcp": {
      "command": "python",
      "args": ["C:\\path\\to\\windbg-mcp\\windbg_mcp.py"]
    }
  }
}

保存后，启动一个新的Codex会话。WinDbg工具将可供模型调用。

Cursor

1. 打开 Cursor → Preferences → Cursor Settings。
2. 导航到 MCP 标签页。
3. 点击 添加新的全局MCP服务器 并使用以下配置：```json { "windbg-mcp": { "command": "python", "args": ["C:\path\to\windbg-mcp\windbg_mcp.py"] } }

4. 保存。Cursor 将在下一次 Composer 会话时连接到服务器。

---

### Continue.dev

在你的 `~/.continue/config.json`（或工作区级别的 `.continue/config.json`）中添加以下内容：```json
{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "python",
          "args": ["C:\\path\\to\\windbg-mcp\\windbg_mcp.py"]
        }
      }
    ]
  }
}

重新加载 Continue 扩展。55 个调试器工具将出现在工具列表中。

自定义代理与 MCP SDK

如果您正在构建自己的代理或自动化流水线，可以通过标准的 MCP stdio 传输连接到 WinDbg MCP。该服务器通过 stdin/stdout 使用 JSON-RPC 2.0 协议进行通信。

Python（使用 mcp SDK）```python

import asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client

server_params = StdioServerParameters( command="python", args=[r"C:\path\to\windbg-mcp\windbg_mcp.py"], )

async def main(): async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: await session.initialize()

        # List all available tools
        tools = await session.list_tools()
        print([t.name for t in tools.tools])

        # Load a crash dump
        result = await session.call_tool(
            "load_dump",
            arguments={"path": r"C:\crashes\crash.dmp"},
        )
        print(result.content)

        # Read 64 bytes at RSP
        result = await session.call_tool(
            "read_mem",
            arguments={"addr": "0x00000000001FF000", "size": 64},
        )
        print(result.content)

asyncio.run(main())

#### TypeScript / Node.js（使用 `@modelcontextprotocol/sdk` 包）```typescript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "python",
  args: ["C:\\path\\to\\windbg-mcp\\windbg_mcp.py"],
});

const client = new Client({ name: "my-agent", version: "1.0.0" }, {});
await client.connect(transport);

// Call a tool
const result = await client.callTool({
  name: "load_dump",
  arguments: { path: "C:\\crashes\\crash.dmp" },
});
console.log(result.content);

await client.close();

LangChain / LangGraph```python

from langchain_mcp_adapters.tools import load_mcp_tools from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client

server_params = StdioServerParameters( command="python", args=[r"C:\path\to\windbg-mcp\windbg_mcp.py"], )

async def get_tools(): async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: await session.initialize() return await load_mcp_tools(session)

#### 通过 stdio 的直接 JSON-RPC（语言无关）

服务器通过换行分隔的 JSON-RPC 2.0 消息进行通信。你可以通过写入进程的标准输入并从标准输出读取，用任何语言驱动它：```
→ {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0"}}}
← {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{...},"serverInfo":{"name":"WinDbg MCP","version":"1.0.0"}}}

→ {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"load_dump","arguments":{"path":"C:\\crashes\\crash.dmp"}}}
← {"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"{\"status\": \"ok\", ...}"}]}}

可用工具（共55个）

会话管理

create — 在调试器下启动一个新进程。设置 initial_break=True（默认）可在进程入口点中断。

attach — 附加到一个正在运行的进程。提供 pid（整数）或 name（进程文件名），不能同时提供两者。

kernel_attach — 连接到远程内核调试器。connect_string 使用 KD 语法，例如 "net:port=55000,key=1.2.3.4"。

load_dump — 打开一个 .dmp 文件进行事后分析。立即返回崩溃地址和最近的符号。

connect — 连接到进程服务器以进行远程用户模式调试。options 使用 DbgEng 连接语法，例如 "tcp:server=192.168.1.10,port=5555"。

执行控制

go — 恢复执行并阻塞，直到下一个调试事件（断点、异常或超时）。返回新的 RIP 以及在运行期间收集的任何捕获。

step_into — 单步进入下一条指令，跟随调用进入被调用的函数。

step_over — 单步跳过下一条指令，将调用视为单步。

step_out — 一直运行直到当前函数返回。

goto — 一直运行直到到达特定符号或十六进制地址，例如 "Kernel32!ExitProcess" 或 "0x7fff12340000"。

trace — 执行 N 次单步迭代，并记录每次访问的指令。

断点

bp — 在符号或地址处设置软件（代码）断点。

• expr：符号（"ntdll!NtCreateFile"）或十六进制地址（"0x7ff800001234"）
• capture：当为 true（默认）时，每次此断点触发时自动保存完整状态——寄存器、栈、内存——到捕获缓冲区
• action："go"（默认）在捕获后继续执行；"break" 则暂停
• oneshot：断点触发一次后移除
• passcount：仅在该位置经过 N 次后触发

hw_bp — 设置硬件/数据断点（监视点）。

• addr：要监视的十六进制地址
• size：监视宽度（字节）——1、2、4 或 8（默认 4）
• access："e" 执行，"w" 写入（默认），"r" 读/写
• capture、action、oneshot：语义与 bp 相同

list_bps — 返回所有当前活动的断点，包括其 ID、表达式、类型和设置。

remove_bp / enable_bp / disable_bp — 通过 bp 或 hw_bp 返回的 id 管理断点。

状态捕获

设置 capture: true（默认）的断点每次触发时会自动保存完整的调试器快照。快照包括所有寄存器、调用栈、RSP 处的 64 字节栈内存以及 RIP 处的 32 字节代码。快照累积在缓冲区中，可通过 get_captures 随时检索。

get_captures — 返回自上次 clear_captures 以来收集的所有捕获。每个捕获包含：

• registers — 所有寄存器值，格式为 {name: "0x..."} 十六进制字符串
• rip — 捕获时刻的指令指针
• symbol_at_rip — RIP 处最近的符号
• instruction — RIP 处指令的反汇编
• stack — 前 10 个调用栈帧，包含地址和返回地址
• context_memory.stack_at_rsp — RSP 处的 64 字节（十六进制、格式化和 ASCII）
• context_memory.code_at_rip — RIP 处的 32 字节（十六进制和格式化）

clear_captures — 清空捕获缓冲区。在开始新运行前使用。

capture_state — 立即按需捕获当前状态。在已中断时使用，无需等待断点触发。

内存

read_mem — 从 addr 读取 size 个原始字节。返回数据为 hex（紧凑）、formatted（空格分隔的字节）和 ascii（可打印字符，非打印字符显示为 .）。

write_mem — 向内存写入字节。data 为十六进制字符串——空格和 \x 前缀会被自动去除，例如 "90909090"、"\\x90\\x90\\x90\\x90" 或 "90 90 90 90"。

read_ptr — 从 addr 开始读取 count 个连续的指针大小的值（32 位为 4 字节，64 位为 8 字节）。

poi — 解引用 addr 处的单个指针（感兴趣指针）。

read_str — 读取一个以 null 结尾的字符串。设置 wide=true 用于 UTF-16LE（Windows WCHAR）。

dump_mem — 格式化的 dword/指针转储，相当于 WinDbg 中的 dd/dp。

mem_info — 返回包含 addr 的内存页属性：基址、大小、类型、状态和保护标志。

mem_list — 列出目标进程地址空间中的所有虚拟内存区域。

寄存器

get_regs — 返回所有可用寄存器，格式为 {name: "0x..."}。具体集合取决于目标架构（x86 与 x64）。

get_reg — 返回单个寄存器，例如 name="rax"、name="eflags"。

set_reg — 覆盖一个寄存器。value 接受十六进制字符串（"0x1234"）或十进制整数字符串。

get_pc — 返回指令指针及其符号解析，以及该地址处的已解码指令文本。

get_sp — 返回当前栈指针值。

符号与反汇编

resolve — 将符号名称解析为其虚拟地址。使用 Module!Function 格式，例如 "Kernel32!WriteFile"、"ntdll!NtCreateFile"。

find_symbols — 通配符符号搜索，例如 "ntdll!*Alloc*"、"kernel32!*File*"。返回所有匹配的符号字符串。

addr_to_symbol — 反向解析虚拟地址为最近的符号名称。

disasm — 从 addr 开始反汇编 count 条指令。若未指定地址，则默认为当前 RIP。

whereami — 返回给定地址所属模块、函数和偏移量的人类可读描述。

模块

list_modules — 列出目标中加载的所有模块，包括基址和大小。

module_info — 返回特定模块的入口点和节列表（名称、虚拟地址、大小），例如 "kernel32.dll"、"ntdll.dll"。

get_exports — 返回模块的完整导出表，作为字符串列表。

get_imports — 返回模块的完整导入表，作为字符串列表。

线程与栈

list_threads — 列出目标进程中的所有线程。

get_thread — 返回当前活动的线程上下文。

set_thread — 通过线程 ID（来自 list_threads）切换活动线程上下文。

get_stack — 以结构化数据返回调用栈。每个帧包含指令地址、返回地址和帧指针。

get_teb — 返回当前线程的线程环境块地址。

get_peb — 返回进程环境块地址。

进程与实用工具

get_handles — 列出目标进程中所有打开的句柄。

get_bitness — 返回 32 或 64，取决于目标架构。

raw — 执行任何 WinDbg 命令字符串并以文本形式返回输出。作为转义机制，用于未被其他工具覆盖的任何功能：``` raw(cmd="!heap -stat") raw(cmd="dt _PEB @$peb") raw(cmd="!locks") raw(cmd="lm") raw(cmd="!address @rsp")

---

## 典型工作流程

### 漏洞利用验证```
1. create(path="C:/target/vuln.exe", args="exploit_input.bin")
2. bp(expr="vuln!processInput+0x2A", action="break")
3. go(timeout=15000)
4. get_captures()

在 get_captures 中，检查 captures[0].registers.rip：

• "0x4141414141414141" — 您通过 'A' 字节控制 RIP
• 任何与您的模式匹配的值 — 已受控
• 有效外观的地址 — 崩溃但尚未受控

检查 captures[0].context_memory.stack_at_rsp.formatted 以查看栈上的填充、返回地址或 shellcode 字节。

崩溃转储分析```

1. load_dump(path="C:/crashes/crash.dmp")
2. get_regs() → full register state at crash time
3. get_stack(frames=30) → call stack at crash
4. get_sp() → read RSP value
5. read_mem(addr=, size=64) → stack contents
6. disasm() → instructions at the crash address

---

### 堆喷射验证```
1. attach(name="target.exe")
2. hw_bp(addr="0x1001F000", size=8, access="w", action="break")
3. go()
4. get_captures()                            → see what wrote to the spray address
5. read_mem(addr="0x1001EFC0", size=128)     → surrounding memory context

ASLR 检查```

1. create(path="C:/target/target.exe")
2. resolve(name="kernel32!WriteFile") → record base address
3. terminate()
4. create(path="C:/target/target.exe")
5. resolve(name="kernel32!WriteFile") → compare: changed = ASLR on, same = ASLR off

### 远程内核调试```
1. kernel_attach(connect_string="net:port=55000,key=1.2.3.4")
2. list_modules()                        → all loaded kernel modules
3. module_info(name="ntoskrnl.exe")      → entry point and sections
4. raw(cmd="!process 0 0")              → list all processes from kernel context
5. raw(cmd="!pcr")                       → processor control region

线程检查```

1. attach(pid=1234)
2. list_threads() → all thread IDs
3. set_thread(id=2) → switch context
4. get_stack(frames=20) → call stack for that thread
5. get_regs() → registers for that thread
6. get_teb() → TEB address

---

## 提示

**符号路径** — 如果符号解析没有返回结果，请配置微软符号服务器：```
raw(cmd=".sympath srv*C:\\symbols*https://msdl.microsoft.com/download/symbols")
raw(cmd=".reload")

超时调节 — go() 默认超时时间为 30 秒。对于在遇到断点前运行时间更长的目标：``` go(timeout=120000) # 2 minutes go(timeout=300000) # 5 minutes

**地址格式** — 所有 `addr` 参数接受十六进制字符串（`"0x1234abcd"`、`"7fff12340000"`）或普通整数。对于十六进制值，`0x` 前缀是可选的。

**Shellcode 验证** — 捕获后，对预期 shellcode 应加载的地址使用 `read_mem` 和 `disasm`。如果 `disasm` 显示预期的指令，则载荷已完整到达。

**调用 `terminate` 或 `detach` 后** — 所有捕获和断点会被自动清除。调用 `create` 或 `attach` 以开始新会话。

**`capture_state` 与 `get_captures` 的区别** — 当已在断点处停止时，使用 `capture_state` 进行按需快照。使用 `get_captures` 检索在 `go` 调用期间每次触发断点时自动保存的状态。

**内核 `raw` 命令** — 通过 `raw` 可良好运行的常见内核调试扩展：```
raw(cmd="!process 0 0")       → list all processes
raw(cmd="!thread")            → current thread details
raw(cmd="!irql")              → current IRQL
raw(cmd="!pcr")               → processor control region
raw(cmd="!pte <addr>")        → page table entry for an address
raw(cmd="dt nt!_EPROCESS @$proc")  → dump EPROCESS structure

许可证

MIT