mcp-windbg

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 MCP server drives the Windows debuggers - CDB for user mode (dumps and -remote) and KD for kernel targets (-k) - so AI models can analyze Windows crash dumps and debug live user-mode and kernel targets in natural language.

What is this?

An AI-powered tool that bridges LLMs with WinDbg for crash dump analysis and live debugging. Execute debugger commands through natural language queries like "Show me the call stack and explain this access violation" or "Open a kernel session and tell me which driver bugchecked."

What This is Not

Not a magical auto-fix solution. It's a Python wrapper around cdb.exe/kd.exe that leverages LLM knowledge to assist with debugging.

Features

• Crash dump analysis - open a .dmp/.mdmp/.hdmp and 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 by kd.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-script can 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

Quick Start

Prerequisites

• Windows with Debugging Tools for Windows or WinDbg from Microsoft Store - these ship both cdb.exe (user mode) and kd.exe (kernel), which the server auto-detects.
• Python 3.10 or higher
• Any MCP-compatible client (Claude Code, GitHub Copilot, Claude Desktop, Cursor, Windsurf, Cline, etc.)
• Configure the MCP server in your chosen client (see Configuration)

[!TIP] In enterprise environments, MCP server usage might be restricted by organizational policies. Check with your IT team about AI tool usage and ensure you have the necessary permissions before proceeding.

Installation

pip install mcp-windbg

Transport Options

The MCP server supports multiple transport protocols:

Transport	Description	Use Case
stdio (default)	Standard input/output	Local MCP clients like Claude Code, VS Code, Claude Desktop
streamable-http	Streamable HTTP	Modern HTTP clients with bidirectional streaming

Starting with Different Transports

Standard I/O (default):

mcp-windbg
# or explicitly
mcp-windbg --transport stdio

Streamable HTTP:

mcp-windbg --transport streamable-http --host 127.0.0.1 --port 8000

Endpoint: http://127.0.0.1:8000/mcp

Command Line Options

--transport {stdio,streamable-http}  Transport protocol (default: stdio)
--host HOST                              HTTP server host (default: 127.0.0.1)
--port PORT                              HTTP server port (default: 8000)
--cdb-path PATH                          Custom path to cdb.exe
--kd-path PATH                           Custom path to kd.exe (kernel debugging)
--symbols-path PATH                      Custom symbols path
--filter-script PATH                     Python script with process_input/process_output tool text hooks
--timeout SECONDS                        Baseline command/connect timeout, a floor for the per-tool defaults (default: 60)
--verbose                                Enable verbose output

Filter Script Hooks

Use --filter-script to load a small Python helper that rewrites tool text only (for example, to redact PII) without seeing the full MCP JSON-RPC envelope:

mcp-windbg --filter-script C:\filters\pii_redaction.py

The script defines process_input and/or process_output callbacks and runs in-process, so treat it as trusted code. See Redact sensitive data for the callback contract and a worked example.

Configuration

mcp-windbg works with any MCP client. The two most common setups are below; see the client configuration guide for Claude Desktop, Copilot CLI, Autohand Code, HTTP, and from-source.

Claude Code - register the server from the command line:

claude mcp add mcp-windbg -s user -e _NT_SYMBOL_PATH="SRV*C:\Symbols*https://msdl.microsoft.com/download/symbols" -- python -m mcp_windbg

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"
            }
        }
    }
}

Prefer not to install the package? Replace python -m mcp_windbg with uvx --from git+https://github.com/svnscha/mcp-windbg mcp-windbg in either setup to fetch and run the server on demand.

Once configured, restart your MCP client and start debugging:

Analyze the crash dump at C:\dumps\app.dmp

MCP Compatibility

This server implements the Model Context Protocol (MCP), making it compatible with any MCP-enabled client:

The beauty of MCP is that you write the server once, and it works everywhere. Choose your favorite AI assistant!

Tools

Every open_* tool returns an opaque session_id (e.g. cdb-1a2b3c4d); pass it to the matching run_*, close_*, and send_ctrl_break calls. User-mode targets (dumps and -remote) run under cdb.exe; kernel targets run under kd.exe.

Tool	Purpose	Use Case
list_dumps	List crash dump files	Discovery and batch analysis
open_cdb_dump	Open and triage a crash dump (cdb.exe)	Initial crash dump analysis → session_id
open_cdb_remote	Attach to a user-mode remote debug server (-remote)	Live user-mode sessions → session_id
open_kd_session	Attach to a kernel target (-k, kd.exe)	KDNET, named pipe, or serial → session_id
run_cdb_command	Run a command on a user-mode session	Custom analysis, by session_id
run_kd_command	Run a command on a kernel session	Kernel investigation, by session_id
close_cdb_session	Close a user-mode session	Resource management, by session_id
close_kd_session	Close a kernel session	Resource management, by session_id
send_ctrl_break	Break into a running live session	Interrupt a running target, by session_id

Each run_* / open_* call accepts an optional timeout_seconds to override the per-tool default (open_cdb_dump 180s, run_cdb_command 60s, run_kd_command 120s, connects 60s). On a live session a command that outruns its timeout is broken into with CTRL+BREAK and the session is resynchronized, so it never wedges.

Documentation

Documentation

Topic	Description
Getting Started	Quick setup and first crash dump analysis
Use cases	Analyze a dump, debug a remote or kernel target, triage many dumps
Command-line options	Every CLI flag, transports, and filter hooks
Tools Reference	The MCP tools and their parameters
Client configuration	Claude Code, VS Code, Claude Desktop, Copilot CLI, pip, and source
Troubleshooting	Common issues and solutions
Development	Run from a local checkout and point a client at the dev build

Examples

Crash Dump Analysis

Analyze this heap address with !heap -p -a 0xABCD1234 and check for buffer overflow"

Execute !peb and tell me if there are any environment variables that might affect this crash"

Run .ecxr followed by k and explain the exception's root cause"

Remote Debugging

"Connect to tcp:Port=5005,Server=192.168.0.100 and show me the current thread state"

"Send CTRL+BREAK to the live session, then dump all thread stacks with ~*k"

"Check for timing issues in the thread pool with !runaway and !threads"

"Show me all threads with ~*k and identify which one is causing the hang"

Kernel Debugging

"Open a kernel session on net:port=50000,key=1.2.3.4 and show the target version" (returns a session_id)

"Using that session, break in, run !analyze -v, and tell me which driver caused the bugcheck"

Blog

Read about the development journey: The Future of Crash Analysis: AI Meets WinDbg

Links

• Reddit: I taught Copilot to analyze Windows Crash Dumps
• Hackernews: AI Meets WinDbg

Star History

License

MIT