Ramana Reddy Polaka
5bf4213313
## What this changes
When the debugger process exits, the session now notices at once and
raises
`DebuggerExitedError` with the exit code and the debugger's last output,
instead
of waiting out the full timeout and then reporting a timeout.
- `debug_session.py`: when the reader thread reaches EOF, it marks the
session as
exited, publishes the last output it collected, and sets `ready_event`
so
waiters wake up. Every marker waiter (`_send_marked`,
`_wait_for_prompt`,
`_wait_for_break_locked`) and every stdin write checks for the exit and
raises
`DebuggerExitedError`, a `DebuggerError` subclass, so the server's
existing
error handling is unchanged. The probes (`_still_running`,
`_resume_took_effect`,
`_break_in_and_resync`) pass this error through rather than treating it
as
"target still running". Once the debugger has exited, `send_command`
fails fast
and says to close the session and open a new one.
- `kd_session.py`: a new `_on_debugger_exit` hook releases the
connect-banner
wait, so kd exiting before it connects is reported at once with kd's own
message.
- Nonzero exit codes are shown in hex (e.g. `0xC0000005`, `0x8007274C`),
since
they are usually NTSTATUS/HRESULT values.
## Why
The reader loop returned silently at EOF, and nothing woke the waiting
thread.
So whenever cdb/kd exited - `q`, `.kill` on a dump, a failed `-remote`
or `-k`
connect, or the debugger itself crashing - every pending call sat out
its whole
timeout (up to 300s for `wait_for_break`) and then reported the wrong
cause:
- `run_cdb_command("q")` -> `Command timed out after N seconds: q
(session may
need a manual break-in)`
- `open_cdb_remote` with a mistyped server -> `Debugger initialization
timed out`,
and cdb's actual reason was thrown away
- `open_kd_session` with a bad `-k` string or a busy KDNET port -> a
connect
timeout that hid kd's error
## How it was verified
Against real cdb (WinDbg 1.2606.22001.0, Store install):
| Case | Before | After |
|---|---|---|
| `q` on `DemoCrash1.exe.7088.dmp` | full timeout, then "timed out" |
fails at once: `Debugger process exited (exit code 0) while running
'q'.` |
| `open_cdb_remote` to an unreachable `tcp:Port=5999,Server=127.0.0.1` |
60s, then "Debugger initialization timed out" | 2.3s: `exit code
0x8007274C`, plus `DebugConnect failed, Win32 error 0n10060 ...` |
New hermetic tests, using the fake cdb/kd:
- the debugger exits during a command (`q`), and later commands fail
fast
- the debugger crashes mid-command; the error carries the exit status
and its last output
- the debugger exits during startup; the error carries its message
- `wait_for_break` ends when the debugger exits
- kd exits before the connect banner
Full suite: `uv run pytest src/mcp_windbg/tests/` - 116 passed, 2
skipped (the
kernel scenarios, since no `MCP_WINDBG_KERNEL_CONNECTION` target was
configured).
Co-authored-by: Sven Scharmentke <sven.scharmentke@liasoft.de>
MCP Server for WinDbg Crash Analysis
A Model Context Protocol server that bridges AI models with WinDbg for crash dump analysis, user-mode remote debugging, and kernel debugging.
Overview
This server drives the Windows debuggers - CDB for user mode (dumps and -remote) and KD for kernel targets (-k) - so you can debug in natural language: "Show me the call stack and explain this access violation" or "Open a kernel session and tell me which driver bugchecked."
It is not a magical auto-fix. It is a Python wrapper around cdb.exe / kd.exe that lets an LLM run real debugger commands and reason about the output.
Features
- Crash dump analysis - open a
.dmp/.mdmp/.hdmpand get automated triage (!analyze -v, stacks, modules, threads) in a single call. - User-mode remote debugging - attach to a live
cdb/WinDbg debug server (-remote) over TCP, a named pipe, or COM, and break in on demand. - Kernel debugging - attach to a kernel target (
-k, driven bykd.exe) over KDNET, a named pipe, or serial; the server waits for the target and breaks in for you. - Run any WinDbg/KD command - drive an open session with arbitrary commands (
kb,!process 0 0,!heap,lm, ...) described in natural language. - Session ids - every open returns a session id; several sessions (dumps, remote, kernel) can be open at once and are addressed independently.
- Resilient live sessions - per-call timeouts, and a slow live command that outruns its timeout is broken into with CTRL+BREAK and the session resynchronized instead of wedging.
- Multi-dump triage - discover and compare many dumps across a directory.
- Text filter hooks - a
--filter-scriptcan redact PII/secrets from tool arguments and output before they leave the machine. - stdio or HTTP - run locally over stdio, or as a streamable-HTTP service you drive from another machine.
Use cases
| You have | You want to | Guide |
|---|---|---|
A .dmp from a crash |
Root-cause it: exception, faulting frame, why it happened | Analyze a crash dump |
A live user-mode process (via cdb -server) |
Break in and inspect a hang or live state | Debug a remote target |
| A KD-enabled machine or VM | Debug drivers, bugchecks, and boot-time issues | Debug a kernel target |
| A folder full of dumps | Triage the batch and find the common signature | Triage multiple dumps |
| A debugging host, but you work elsewhere | Drive it over HTTP from another machine | Debug from another machine |
| Dumps with secrets or PII | Scrub tool output before it leaves the box | Redact sensitive data |
Tools
Every open_* tool returns an opaque session_id (e.g. cdb-1a2b3c4d); pass it to the matching run_*, close_*, send_ctrl_break, and wait_for_break calls. User-mode targets (dumps and -remote) run under cdb.exe; kernel targets run under kd.exe.
| Tool | Purpose |
|---|---|
list_dumps |
List crash dump files in a directory |
open_cdb_dump |
Open and triage a crash dump |
open_cdb_remote |
Attach to a user-mode remote debug server (-remote) |
open_kd_session |
Attach to a kernel target (-k, KDNET / named pipe / serial) |
run_cdb_command |
Run a command on a user-mode session |
run_kd_command |
Run a command on a kernel session |
close_cdb_session |
Close a user-mode session |
close_kd_session |
Close a kernel session (resumes the target machine) |
send_ctrl_break |
Break into a running live session |
wait_for_break |
Wait for a target you resumed with g to stop again |
Parameters, timeouts, and the built-in triage prompts are in the tools reference.
Quick start
Note
Claude Code in enterprise environments: when managed settings define
allowedMcpServers, plugin-bundled MCP servers may be silently skipped (Claude Code issue #32882). I recommend installing and registering the server manually, then optionally adding the skills or agents plugin. The server must still be permitted by your organization's MCP policy.
Prerequisites
- Windows with Debugging Tools for Windows or WinDbg from the Microsoft Store, which ship
cdb.exeandkd.exe(auto-detected). - Any MCP-compatible client (Claude Code, GitHub Copilot, Claude Desktop, Cursor, Windsurf, Cline, ...).
Python is not a prerequisite in itself. Each route below states what it needs.
Install in Claude Code
Install the server plugin if needed, then optionally add skills, agents, or both:
| Plugin | Server | Included workflows |
|---|---|---|
mcp-windbg-uvx |
Launched by the plugin with uvx | MCP tools only |
mcp-windbg-skills |
Uses the uvx plugin or your own MCP connection | Four optional skills |
mcp-windbg-agents |
Uses the uvx plugin or your own MCP connection | Optional crash-analyst agent |
Server with uvx
The shortest path: two lines, no pip install, no MCP configuration to edit. Adds the
ten tools, with symbols preconfigured. Skills and agents are installed separately.
/plugin marketplace add svnscha/mcp-windbg
/plugin install mcp-windbg-uvx@mcp-windbg
Needs uv, which supplies uvx: winget install astral-sh.uv. The
plugin uses it to fetch the pinned server from PyPI on first use, so there is nothing else to
install. See the plugin README for symbols and options.
Registering the server yourself
If you would rather not use the plugin, or you already run the package:
pip install mcp-windbg
claude mcp add mcp-windbg -s user -e _NT_SYMBOL_PATH="SRV*C:\Symbols*https://msdl.microsoft.com/download/symbols" -- python -m mcp_windbg
Needs Python 3.10 or higher. Add either optional plugin below for guided workflows or an agent.
Skills for an existing server
After installing the uvx plugin or registering mcp-windbg yourself, optionally add the four skills:
/plugin marketplace add svnscha/mcp-windbg
/plugin install mcp-windbg-skills@mcp-windbg
Invoke /mcp-windbg-skills:analyze-dump, /mcp-windbg-skills:debug-remote,
/mcp-windbg-skills:kernel-debug, or /mcp-windbg-skills:windbg-doctor.
This plugin uses your configured MCP connection and adds no server, runtime,
symbol settings, or crash-analyst agent. It works with a native executable,
Python installation, or HTTP service exposing the mcp-windbg tools.
Install this plugin alongside uvx for the server and skills together, or omit it to use just the tools.
When upgrading from a version that bundled skills, install this plugin to keep the workflows;
their invocation prefix changes from /mcp-windbg: to /mcp-windbg-skills:.
The server's built-in MCP prompts
remain available independently of these plugins. See the
plugin guide for updating or switching plugins.
Agents for an existing server
/plugin marketplace add svnscha/mcp-windbg
/plugin install mcp-windbg-agents@mcp-windbg
Ask: "Use the mcp-windbg-agents:crash-analyst agent on C:\dumps\app.dmp". It investigates the dump and returns a verdict, evidence, and next steps through your existing MCP connection. It requires neither uvx nor the skills plugin. When upgrading from a version that bundled the agent, install this plugin to keep it.
Install in another client
pip install mcp-windbg
Needs Python 3.10 or higher. Then point the client at python -m mcp_windbg. For VS Code
(GitHub Copilot), press F1 and select MCP: Open User Configuration to enable it in every
workspace:
{
"servers": {
"mcp_windbg": {
"type": "stdio",
"command": "python",
"args": ["-m", "mcp_windbg"],
"env": {
"_NT_SYMBOL_PATH": "SRV*C:\\Symbols*https://msdl.microsoft.com/download/symbols"
}
}
}
}
See the client configuration guide for Claude Desktop, Copilot CLI, Autohand Code, HTTP, and from-source setups.
Start debugging
Restart your client, then ask for what you want:
Analyze the crash dump at C:\dumps\app.dmp
Connect to tcp:Port=5005,Server=192.168.0.100 and show me the current thread state
Open a kernel session on net:port=50000,key=1.2.3.4, run !analyze -v, and tell me which driver bugchecked
Server options (--cdb-path, --kd-path, --symbols-path, --filter-script, --transport, ...) are documented in the command-line reference.
Documentation
| Topic | Description |
|---|---|
| Getting started | Setup and your first crash dump analysis |
| Analyze a crash dump | Root-cause an exception: faulting frame, why it happened |
| Debug a remote target | Break into a live user-mode process and inspect a hang |
| Debug a kernel target | Drivers, bugchecks, and boot-time issues over KDNET or a pipe |
| Triage multiple dumps | Scan a folder and find the common signature |
| Debug from another machine | Run the server over HTTP and drive it remotely |
| Redact sensitive data | Scrub secrets from tool output before it leaves the box |
| Reference | Tools, prompts, CLI options, and client configuration |
| Troubleshooting | Common issues and solutions |
| Development | Run from a local checkout and point a client at the dev build |
Blog
Read about the development journey: The Future of Crash Analysis: AI Meets WinDbg
License
MIT