WinDbg GUI MCP Server

一个为 WinDbg GUI 版本设计的 Model Context Protocol (MCP) 服务器，通过 PyKD 插件实现与 WinDbg 的集成。

架构设计

采用插件 + MCP 服务器的方式：

┌─────────────┐         JSON-RPC          ┌──────────────────┐
│             │    (HTTP:13338/windbg)    │                  │
│  MCP 客户端  │◄─────────────────────────►│  MCP 服务器      │
│  (AI助手)   │                            │  (Python)        │
└─────────────┘                            └──────────────────┘
                                                     │
                                                     │ JSON-RPC
                                                     ▼
                                           ┌──────────────────┐
                                           │  WinDbg 插件     │
                                           │  (PyKD + HTTP)   │
                                           └──────────────────┘
                                                     │
                                                     │ PyKD API
                                                     ▼
                                           ┌──────────────────┐
                                           │    WinDbg GUI    │
                                           └──────────────────┘

组件

WinDbg 插件 - 在 WinDbg 中通过 PyKD 加载，启动 HTTP 服务器
MCP 服务器 - 实现 MCP 协议，与 AI 助手通信

前置要求

Windows 操作系统
WinDbg（包含在 Windows SDK 或 Windows Store 版本）
Python 3.11 或更高版本
PyKD：WinDbg 的 Python 扩展

安装步骤

1. 安装 PyKD

pip install pykd

或从官方下载：https://githomeup.com/pykd/pykd/releases

2. 安装 MCP 服务器

cd windbg-gui-mcp
pip install -e .

3. 在 WinDbg 中加载插件

在 WinDbg 中执行以下命令：

.load pykd
!py C:\path\to\windbg-gui-mcp\src\windbg_gui_mcp\windbg_plugin.py

你应该看到：

[WinDbg MCP] Server started at http://localhost:13338

配置 MCP 客户端

Visual Studio Code (Cline/Roo Code)

编辑 cline_mcp_settings.json 或 mcp_settings.json：

{
  "mcpServers": {
    "windbg-gui-mcp": {
      "command": "python",
      "args": [
        "-m",
        "windbg_gui_mcp"
      ],
      "timeout": 1800,
      "disabled": false
    }
  }
}

Claude Desktop

编辑 claude_desktop_config.json：

{
  "mcpServers": {
    "windbg-gui-mcp": {
      "command": "python",
      "args": [
        "-m",
        "windbg_gui_mcp"
      ]
    }
  }
}

可用工具

工具	说明
`check_connection()`	检查与 WinDbg 的连接状态
`get_debugger_info()`	获取调试器信息（内核/用户模式、架构等）
`execute_command(command)`	执行任意 WinDbg 命令
`get_stack_trace()`	获取当前调用堆栈
`get_registers()`	获取所有 CPU 寄存器
`get_modules()`	获取加载的模块列表
`read_memory(address, size)`	读取指定地址的内存
`analyze_exception()`	运行 !analyze -v 分析异常
`get_threads()`	获取所有线程信息

使用示例

基本调试

检查 WinDbg 连接

获取当前的调用堆栈

显示所有寄存器的值

内存分析

读取地址 0x00401000 处的 64 字节内存

执行命令: dt ntdll!_PEB @$peb

异常分析

分析当前异常并给出详细报告

执行命令: !analyze -v

高级功能

自定义 WinDbg 命令

你可以在 windbg_plugin.py 中添加新的 JSON-RPC 方法：

@jsonrpc
def my_custom_command(param: Annotated[str, "Description"]) -> str:
    """My custom WinDbg command"""
    result = pykd.dbgCommand(f"!myext.mycmd {param}")
    return result

然后在 server.py 中添加对应的 MCP 工具：

@mcp.tool()
def my_custom_command(param: str) -> str:
    """My custom WinDbg command"""
    return make_jsonrpc_request("my_custom_command", param)

故障排除

无法连接到 WinDbg

确认 PyKD 已正确加载：
```
.chain  # 查看加载的扩展
```
确认插件服务器正在运行：
```
!py print("Test")  # 测试 PyKD
```
检查端口占用：
```
netstat -ano | findstr 13338
```

PyKD 导入错误

确保 PyKD 安装在 WinDbg 使用的 Python 环境中：

# 查看 WinDbg 使用的 Python 版本
!py import sys; print(sys.version)

# 在该环境中安装 PyKD
python -m pip install pykd

插件崩溃

如果插件导致 WinDbg 崩溃，可以：

在加载前设置断点：
```
sxe ld pykd
```

查看详细错误：

!py import traceback; traceback.print_exc()

开发

运行测试

pytest tests/

生成配置

python -m windbg_gui_mcp --config

许可证

MIT License

致谢

本项目参考了以下优秀项目：

IDA Pro MCP - 架构设计参考
mcp-windbg - CDB 实现参考
PyKD - WinDbg Python 扩展

windbg-mcp