Content
# Windbg-MCP
MCP (Model Context Protocol) server for WinDbg — Enable AI-driven kernel debugging.
## How it Works
```
MCP Client ──HTTP(MCP)──► Windbg-MCP Server ──TCP──► WinDbg (manual control)
.server tcp:port=50000
Dual-machine kernel already connected to VM, already broken
```
- **User** manually interrupts the target in Windbg
- **Windbg** exposes the debugging session via `.server tcp:port=XXXX`
- **Windbg-MCP** connects as a remote client (cdb.exe) and sends/receives commands
- **AI Agent** sends debugging instructions and retrieves results via MCP protocol
## Architecture
```
Server Layer (HTTP/MCP) ← MCP protocol, unchanged
│
Command Layer (25 tools) ← Unified call to execute()
│
Engine Layer ← Define execute(command) → str
└── SubprocessEngine ← Start cdb.exe, pipe communication, UTF-8 fault tolerance
```
- **New debugging mode**: Implement Engine interface
- **New tool**: Add file under `tools/`, register to Command layer
- **Replace transport**: Server layer can be replaced independently without affecting debugging engine
## Quick Start
### Environment Requirements
- Windows 10/11 x64
- [Windows SDK](https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/) (including Debugging Tools)
- Python 3.10+
### Installation
```bash
cd Windbg-MCP
pip install -e .
```
### 1. Target VM Configuration
**KDNET (recommended):**
```bash
# Execute in VM as administrator
bcdedit /debug on
bcdedit /dbgsettings net hostip:<host IP> port:50005 key:1.2.3.4
```
Set VM network to Host-Only, ensure host and VM can communicate.
**Serial port/Pipe:**
```bash
# Execute in VM as administrator
bcdedit /debug on
bcdedit /dbgsettings serial debugport:1 baudrate:115200
```
Add serial port to VM → named pipe `\\.\pipe\com_1`.
### 2. Windbg Connects to Target
```
WinDbg → File → Kernel Debug → Net (or COM)
```
Connect and manually interrupt (Ctrl+Break), then expose TCP:
```
.server tcp:port=50000
```
### 3. Start MCP Server
```bash
python -m src.server --connect tcp:localhost:50000
```
### 4. Configure MCP Client
```json
{
"mcpServers": {
"windbg": {
"type": "remote",
"url": "http://localhost:8080/mcp"
}
}
}
```
### Local User-mode Debugging
Start Windbg GUI → Open Executable / Attach Process / Open Dump → Interrupt:
```
.server tcp:port=50000
```
Open another terminal:
```bash
python -m src.server --connect tcp:localhost:50000
```
Windbg GUI and AI Agent share the same debugging session, without interfering.
## Data Transmission Convention
- **AI ↔ Server**: All parameters are strings, `0x` hexadecimal, register names, and symbol names can be directly passed
- **Server ↔ Windbg**: Server converts string to valid Windbg command and executes
- **Output**: Text returned to Agent as is
## Available Tools
`windbg_exec` transparently covers all WinDbg commands, listing all functions and corresponding tools.
### I. Execution Control
| WinDbg Command | Function | MCP Tool |
|-------------|------|----------|
| `g` Go | Continue running | `windbg_go` |
| `p` Step | Step over | `windbg_step_over` |
| `t` Trace | Step into | `windbg_step_into` |
| `gu` Go Up | Step out | `windbg_step_out` |
| `pa` Step to Address | Step to address | `windbg_exec` |
| `pc` Step to Next Call | Step to call | `windbg_exec` |
| `pt` Step to Return | Step to return | `windbg_exec` |
| `gc/gh/gn/gN` | Conditional/Exception continue | `windbg_exec` |
### II. Breakpoints
| WinDbg Command | Function | MCP Tool |
|-------------|------|----------|
| `bp/bu/bm` Set Breakpoint | Set breakpoint | `windbg_bp_set` |
| `bl` Breakpoint List | List breakpoints | `windbg_bp_list` |
| `bc` Breakpoint Clear | Clear breakpoint | `windbg_bp_clear` |
| `bd` Breakpoint Disable | Disable breakpoint | `windbg_bp_disable` |
| `be` Breakpoint Enable | Enable breakpoint | `windbg_bp_enable` |
| `ba` Break on Access | Memory access breakpoint | `windbg_exec` |
| `br` Breakpoint Renumber | Renumber | `windbg_exec` |
| `bs` Update Breakpoint Command | Update breakpoint command | `windbg_exec` |
| `bsc` Update Conditional BP | Update conditional breakpoint | `windbg_exec` |
### III. Memory Operations
| WinDbg Command | Function | MCP Tool |
|-------------|------|----------|
| `db/dd/dq/du/da...` Display Memory | Read memory | `windbg_mem_read` |
| `eb/ed/eq...` Enter Values | Write memory | `windbg_mem_write` |
| `s` Search Memory | Search memory | `windbg_mem_search` |
| `c` Compare Memory | Compare memory | `windbg_exec` |
| `f` Fill Memory | Fill memory | `windbg_exec` |
| `m` Move Memory | Move memory | `windbg_exec` |
| `dds/dps/dqs` Words & Symbols | Symbolic display | `windbg_exec` |
| `dl` Display Linked List | Display linked list | `windbg_exec` |
| `ds` Display String | Display string | `windbg_exec` |
### IV. Registers
| WinDbg Command | Function | MCP Tool |
|-------------|------|----------|
| `r` Registers | Read/write registers | `windbg_reg_read` / `windbg_reg_write` |
| `rm` Register Mask | Register mask | `windbg_exec` |
| `rdmsr/wrmsr` | Read/write MSR | `windbg_exec` |
### V. Disassembly
| WinDbg Command | Function | MCP Tool |
|-------------|------|----------|
| `u` Unassemble | Disassemble | `windbg_disasm` |
| `uf` Unassemble Function | Disassemble entire function | `windbg_exec` |
| `up` Unassemble Physical | Physical address disassemble | `windbg_exec` |
| `a` Assemble | Assemble and write | `windbg_exec` |
| `#` Search Disasm Pattern | Disassemble pattern search | `windbg_exec` |
### VI. Stack Frames
| WinDbg Command | Function | MCP Tool |
|-------------|------|----------|
| `k/kb/kp/kP/kv` Stack Backtrace | Call stack (Markdown table) | `windbg_stack` |
| `.frame` Set Current Frame | Switch frame | `windbg_exec` |
| `dv` Display Local Variables | Local variables | `windbg_stack_frame` |
| `wt` Trace and Watch Data | Trace and watch | `windbg_exec` |
### VII. Symbols
| WinDbg Command | Function | MCP Tool |
|-------------|------|----------|
| `x` Examine Symbols | Search symbols | `windbg_sym_lookup` |
| `ln` List Nearest Symbols | Address → symbol name | `windbg_sym_name` |
| `ld` Load Symbols | Load symbols | `windbg_exec` |
| `.sympath` Set Symbol Path | Symbol path | `windbg_exec` |
| `.reload` Reload Module | Reload module | `windbg_exec` |
### VIII. Types & Expressions
| WinDbg Command | Function | MCP Tool |
|-------------|------|----------|
| `dt` Display Type | Display type structure | `windbg_dt` |
| `?` Evaluate Expression | MASM expression evaluation | `windbg_eval` |
| `??` Evaluate C++ Expression | C++ expression evaluation | `windbg_eval` |
### IX. Processes & Threads
| WinDbg Command | Function | MCP Tool |
|-------------|------|----------|
| `!process` | Process enumeration/details | `windbg_process_list` / `windbg_process_info` |
| `|` Process Status | Process status | `windbg_exec` |
| `|s` Set Current Process | Switch process | `windbg_exec` |
| `~` Thread Status | Thread status | `windbg_exec` |
| `~s` Set Current Thread | Switch thread | `windbg_exec` |
| `~f/~u` Freeze/Unfreeze | Freeze/unfreeze thread | `windbg_exec` |
| `~n/~m` Suspend/Resume | Suspend/resume thread | `windbg_exec` |
| `!thread` | Thread details | `windbg_exec` |
| `!peb` / `!teb` | PEB/TEB information | `windbg_exec` |
### X. Modules & Drivers
| WinDbg Command | Function | MCP Tool |
|-------------|------|----------|
| `lm` List Loaded Modules | List modules | `windbg_module_list` |
| `!drvobj` | Driver object information | `windbg_exec` |
| `!devnode` / `!devstack` | Device node/stack | `windbg_exec` |
| `!devobj` | Device object | `windbg_exec` |
### XI. Crash Analysis
| WinDbg Command | Function | MCP Tool |
|-------------|------|----------|
| `!analyze -v` | Automated crash analysis | `windbg_analyze` |
| `.bugcheck` | BugCheck code and parameters | `windbg_bugcheck` |
| `.dump` Create Dump | Create dump file | `windbg_exec` |
| `.crash` Force Crash | Force crash | `windbg_exec` |
| `.ecxr` Exception Context | Exception context record | `windbg_exec` |
| `.exr` Exception Record | Exception record | `windbg_exec` |
| `sx/sxd/sxe/sxi` | Exception control | `windbg_exec` |
### XII. Kernel-specific
| WinDbg Command | Function | MCP Tool |
|-------------|------|----------|
| `!irql` | View IRQL level | `windbg_exec` |
| `!locks` | Lock information | `windbg_exec` |
| `!handle` | Handle information | `windbg_exec` |
| `!vm` | Virtual memory statistics | `windbg_exec` |
| `!memusage` | Physical memory statistics | `windbg_exec` |
| `!poolused` / `!poolfind` | Memory pool statistics | `windbg_exec` |
| `!object` | Kernel object | `windbg_exec` |
| `!idt` / `!gdt` / `!tss` | Descriptor tables | `windbg_exec` |
| `!sysinfo` / `!cpuid` | System/CPU information | `windbg_exec` |
| `!pcr` / `!prcb` | Processor control region | `windbg_exec` |
| `!cs` / `!dpcs` / `!apc` | Critical region/DPC/APC | `windbg_exec` |
| `!ioapic` / `!pic` | APIC/PIC information | `windbg_exec` |
| `!pfn` | PFN database | `windbg_exec` |
### XIII. Sessions & Status
| WinDbg Command | Function | MCP Tool |
|-------------|------|----------|
| `.lastevent` | Last event | `windbg_status` |
| `||` System Status | System status | `windbg_exec` |
| `.server` / `.endsrv` | Debugging server | `windbg_exec` |
| `q/qd` Quit/Detach | Quit/detach | `windbg_exec` |
| `version` / `vertarget` | Version information | `windbg_exec` |
| `n` Set Number Base | Set radix | `windbg_exec` |
### Transparent
| Tool | Parameter | Description |
|------|------|------|
| `windbg_exec` | command | Execute arbitrary Windbg command, completed by `windbg_exec` |
## CLI Parameters
```
python -m src.server [options]
--connect tcp:HOST:PORT Connect to existing Windbg (default localhost:50000)
--standalone Independent debugging (no Windbg GUI)
--pid PID Attach process (--standalone)
--exe PATH Launch executable (--standalone)
--dump PATH Load dump (--standalone)
--http-port PORT HTTP port (default 8080)
--debug-json Print raw JSON transmission
```
## Configuration
| Environment Variable | Default Value | Description |
|----------|--------|------|
| `WINDBG_MCP_HTTP_PORT` | 8080 | HTTP service port |
| `WINDBG_MCP_DEBUG_PORT` | 50000 | Windbg TCP port |
| `WINDBG_MCP_DEBUG_HOST` | 127.0.0.1 | Windbg TCP address |
| `WINDBG_MCP_TIMEOUT` | 30 | Command timeout (seconds) |
| `WINDBG_MCP_RETRIES` | 3 | Automatic retry times |
| `WINDBG_MCP_DEBUG_JSON` | — | Set to 1 to enable JSON debugging output |
## FAQs
### Tool returns empty / timeout?
1. Confirm target interrupted in Windbg (Ctrl+Break)
2. Confirm `.server tcp:port=50000` still listening, use `.server` to view
3. Change port and reopen: `.server tcp:port=50001`, then `--connect tcp:localhost:50001`
### Encoding error (read_loop died)?
cdb.exe output contains non-GBK characters may trigger. Engine has built-in `encoding="utf-8"` + `errors="replace"` fault tolerance.
### Port occupied?
```
.endsrv 0 # Close old service
.server tcp:port=50002 # Change port and reopen
```
### Multiple VMs debugging simultaneously?
Launch multiple MCP Server instances, bind different ports.
## Development
```bash
pip install -e ".[dev]"
pytest
```
### Debug raw JSON
```bash
python -m src.server --debug-json
# or
WINDBG_MCP_DEBUG_JSON=1 python -m src.server
```
Output format:
```
=== REQUEST ===
{
"jsonrpc": "2.0",
"id": "1",
"method": "tools/call",
"params": {
"name": "windbg_mem_read",
"arguments": { "address": "0xfffff80012345678", "size": "0x40" }
}
}
=== RESPONSE ===
{
"jsonrpc": "2.0",
"id": "1",
"result": {
"content": [{"type": "text", "text": "fffff800`12345678 00000000 ..."}]
}
}
```
## License
MIT
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available