mcp-windbg 0.15.0

A Model Context Protocol server providing tools to analyze Windows crash dumps using WinDbg/CDB

MCP Server for WinDbg Crash Analysis

A Model Context Protocol server that bridges AI models with WinDbg for crash dump analysis and remote debugging.

Overview

This MCP server integrates with CDB to enable AI models to analyze Windows crash dumps and connect to remote debugging sessions using WinDbg/CDB.

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

What This is Not

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

Usage Modes

• Crash Dump Analysis: Examine Windows crash dumps
• Live Debugging: Connect to remote debugging targets
• Directory Analysis: Process multiple dumps for patterns

Quick Start

Prerequisites

• Windows with Debugging Tools for Windows or WinDbg from Microsoft Store.
• Python 3.10 or higher
• Any MCP-compatible client (GitHub Copilot, Claude Desktop, Cline, Cursor, Windsurf etc.)
• Configure MCP server in your chosen client

[!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 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
--symbols-path PATH                      Custom symbols path
--filter-script PATH                     Python script with process_input/process_output tool text hooks
--timeout SECONDS                        Command timeout (default: 30)
--verbose                                Enable verbose output

Filter Script Hooks

Use --filter-script to load a small Python helper that can rewrite tool text only. The script never sees the full MCP JSON-RPC envelope, which keeps the hook surface smaller and avoids protocol interference.

The script may define either or both of these functions:

def process_input(text, context):
    return text


def process_output(text, context):
    return text

• process_input is applied to string-valued tool arguments before the tool handler runs.
• process_output is applied to TextContent.text values returned by tools before they go back to the client.
• text is always a plain str.
• context includes hook, tool_name, transport, and call_id.
• Input callbacks also receive argument_path such as $.command or $.payload.notes[0].
• Output callbacks also receive content_index for the returned text item.
• call_id is stable for the full lifetime of one tool invocation, so script writers can correlate input and output for the same call.
• A hook may return None to leave the text unchanged, or return a replacement string.

Example redaction filter:

def process_input(text, context):
    if context["tool_name"] == "run_windbg_cmd" and context["argument_path"] == "$.command":
        return text.replace("[e-mail]", "[redacted-email]")
    return text


def process_output(text, context):
    return text.replace("[e-mail]", "[redacted-email]")

Start the server with the filter enabled:

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

The script runs in-process with the server. Treat it as trusted code.

Configuration for Visual Studio Code

To make MCP servers available in all your workspaces, use the global user configuration:

1. Press F1, type > and select MCP: Open User Configuration.
2. Paste the following JSON snippet into your user configuration:

{
    "servers": {
        "mcp_windbg": {
            "type": "stdio",
            "command": "python",
            "args": ["-m", "mcp_windbg"],
            "env": {
                "_NT_SYMBOL_PATH": "SRV*C:\\Symbols*https://msdl.microsoft.com/download/symbols"
            }
        }
    }
}

This enables MCP Windbg in any workspace, without needing a local .vscode/mcp.json file.

To enable a filter script, add it to the args:

"args": ["-m", "mcp_windbg", "--filter-script", "C:\\filters\\pii_redaction.py"]

HTTP Transport Configuration

For scenarios where you need to run the MCP server separately (e.g., remote access, shared server, or debugging the server itself), you can use the HTTP transport:

1. Start the server manually:

python -m mcp_windbg --transport streamable-http --host 127.0.0.1 --port 8000

2. Configure VS Code to connect via HTTP:

{
    "servers": {
        "mcp_windbg_http": {
            "type": "http",
            "url": "http://localhost:8000/mcp"
        }
    }
}

Workspace-specific and alternative configuration: See the client configuration guide for details on configuring Claude Desktop, Copilot CLI, and other clients, or for workspace-only setup.

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

Tool	Purpose	Use Case
list_windbg_dumps	List crash dump files	Discovery and batch analysis
open_windbg_dump	Analyze crash dumps	Initial crash dump analysis
close_windbg_dump	Cleanup dump sessions	Resource management
open_windbg_remote	Connect to remote debugging	Live debugging sessions
close_windbg_remote	Cleanup remote sessions	Resource management
run_windbg_cmd	Execute WinDbg commands	Custom analysis and investigation
send_ctrl_break	Break into a running target	Interrupt execution during live debugging

Documentation

Documentation

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

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"

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