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

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:

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.

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

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