DOCSEARCHbyAlgolia
Submit Docs

mcp-windbg

repository·main·Indexed 23 days ago

https://github.com/svnscha/mcp-windbg

A Model Context Protocol (MCP) server that enables AI models to perform Windows crash dump analysis, user-mode remote debugging, and kernel debugging by wrapping cdb.exe and kd.exe. It provides a toolset for listing dumps, opening debugging sessions, and executing WinDbg commands via natural language interfaces like Claude Code and GitHub Copilot.

Tokens
22.7K
Snippets
47
Records
118
Agent score
79%

What's inside mcp-windbg

  1. Overview of mcp-windbg

    main

    mcp-windbg is a Model Context Protocol (MCP) server designed to allow AI assistants (like Claude Desktop or GitHub Copilot) to analyze Windows crash dumps and perform live or remote debugging using plain language.

    Instead of manually typing WinDbg commands, you can ask your AI assistant questions like "what caused this access violation?". The server translates these requests into commands for cdb.exe (the console version of WinDbg), executes them, and returns the output to the LLM for explanation.

    Key Capabilities:

    • Crash Dump Analysis: Open .dmp files to inspect exceptions, faulting instructions, call stacks, modules, and threads.
    • Remote Debugging: Connect to live debugging sessions to inspect threads, memory, and state.
    • Triage: Scan folders of dumps to identify common patterns.
    • Remote Server Access: Run the server over HTTP on a Windows host to connect from a different machine.
    • Data Redaction: Scrub sensitive information or PII from tool output before it is sent to a cloud-based LLM.

  2. Select a WinDbg analysis use case

    main

    The mcp-windbg server supports several distinct debugging workflows depending on your available assets. Choose the workflow that matches your current debugging target:

    • Analyze a crash dump: Use when you have a .dmp file. Key tools: open_cdb_dump, run_cdb_command, close_cdb_session.
    • Debug a remote target: Use when you have a live user-mode debugging session. Key tools: open_cdb_remote, send_ctrl_break, run_cdb_command.
    • Debug a kernel target: Use when you have a kernel debug connection (e.g., KDNET, pipe, serial). Key tools: open_kd_session, send_ctrl_break, run_kd_command.
    • Triage multiple dumps: Use when you have a folder containing multiple dump files. Workflow: Use list_dumps, then follow the crash-dump analysis flow for each file.
    • Debug from another machine: Use when you have a Windows debugging host but want to work from a different machine. This is achieved using the HTTP transport.
    • Redact sensitive data: Use when dumps contain secrets or PII. This is achieved by applying a --filter-script over any of the tools above.

  3. Understand the mcp-windbg architecture

    main

    The mcp-windbg system operates through a three-tier interaction model:

    1. MCP Client: An AI client (like Claude Desktop, VS Code, or GitHub Copilot CLI) that initiates requests.
    2. mcp-windbg Executable: The MCP server that receives tool calls from the client. It is initialized and controlled via CLI options.
    3. WinDbg/CDB: The underlying debugger engine (cdb.exe) that the server executes commands against to perform crash analysis.

    In a typical workflow, you configure your client to launch the mcp-windbg executable with specific CLI arguments. Once running, the AI model uses the exposed MCP tools to drive the debugger session.

  4. Understand filter script visibility and safety

    main

    When implementing a filter script, keep the following constraints and behaviors in mind:

    • Scope of Visibility: The filter only sees tool text. This includes string arguments (via process_input) and TextContent output (via process_output). It does not see the raw MCP protocol envelope.
    • Execution Model: The script runs in-process with the server. You must treat the filter script as trusted code.
    • Error Handling: If a hook function raises an exception, the server will not crash; instead, the error is reported as a tool error.

  5. How mcp-windbg works

    main

    The system operates as a bridge between an AI client and the Windows debugger engine. The architecture follows this flow:

    1. MCP Client (e.g., Claude Desktop, GitHub Copilot) communicates with the mcp-windbg server via the Model Context Protocol (over stdio or HTTP).
    2. The mcp-windbg server translates the client's intent into debugger commands.
    3. The server executes these commands using cdb.exe (the WinDbg engine).
    4. cdb.exe interacts directly with the crash dump or the remote target.

    Important Limitations:

    • The server is a wrapper for cdb.exe; it does not automatically fix bugs.
    • It supports dump files and connecting to a debugging server (where cdb/WinDbg was started with the -server flag).
    • Unsupported: Kernel-mode (-k) debugging and attaching to a running process by PID are not supported.

  6. Perform kernel-triage for live kernel targets

    main

    Use the kernel-triage prompt for live kernel debugging over a -k cable. The workflow orients the model (vertarget, !analyze -v, lm) and helps distinguish between a bugchecked machine and one that was simply broken into. It then investigates processes and driver states.

    Note: Because the entire machine is halted while the session is open, the prompt treats releasing the machine (close_kd_session with resume: true) as a critical final step.

    Argument:

    • connection_string (optional): The -k connection string (e.g., net:port=50000,key=1.2.3.4).

  7. How sessions and session IDs work

    main

    The MCP server manages debugger processes (cdb.exe or kd.exe) as persistent sessions.

    1. Initialization: Every open_* tool starts a new debugger process and returns an opaque session_id on the first line of its output (e.g., session_id: cdb-1a2b3c4d).
    2. Interaction: You must pass this session_id to all subsequent calls for that session, such as run_*, close_*, and send_ctrl_break.
    3. Concurrency: Multiple sessions can be open simultaneously, allowing for side-by-side comparison of different dumps or targets.
    4. Session Types:
      • User-mode targets (dumps and -remote) use cdb.exe and the cdb prefixed tools.
      • Kernel targets use kd.exe and the kd prefixed tools.
      • The server enforces a strict match: calling a kd tool with a cdb ID will result in an error.
    5. Cleanup: Always call close_* when finished to release the underlying debugger processes and system resources.
    session_id: cdb-1a2b3c4d

  8. Understand the difference between dumps and live targets

    main

    When choosing a workflow in mcp-windbg, it is important to distinguish between the nature of your target:

    • Dump: A frozen snapshot of a process or system at a specific point in time. You can only read and inspect the state; you cannot advance execution.
    • Remote Target: A live, running session. You can interact with the target, break into execution, and inspect it as it runs.

  10. Manage tool timeouts

    main

    Most open_* and run_* tools accept an optional timeout_seconds parameter to override default behavior. The server-wide --timeout CLI flag acts as a floor for these values.

    Default Timeouts:

    • open_cdb_dump: 180s (includes running !analyze -v)
    • open_cdb_remote: 60s
    • run_cdb_command: 60s
    • run_kd_command: 120s (kernel memory reads can be slow)
    • open_kd_session: 60s

    Behavior on Live Sessions: On a live session (remote or kernel), if a command exceeds its timeout, the server sends a CTRL+BREAK to break into the target and resynchronizes the session. The tool will report a timeout error instead of leaving the session wedged.

  11. Perform remote-triage for live user-mode targets

    main

    Use the remote-triage prompt to investigate a live user-mode target connected via a cdb debugging server. Because the target is live, the model follows an investigation workflow (orienting with r, k, ~, and using !analyze -v or !runaway) and will ask for permission before executing commands that change the target's state. The session is closed at the end to allow the target to resume.

    Argument:

    • connection_string (optional): The -remote connection string (e.g., tcp:Port=5005,Server=192.168.0.100).

  12. Understand mcp-windbg session management

    main

    The server manages multiple debugging sessions (crash dumps, remote user-mode, or kernel) simultaneously.

    Every open_* tool returns an opaque session_id (e.g., cdb-1a2b3c4d). To interact with a specific session, you must pass this session_id to the corresponding run_*, close_*, or send_ctrl_break calls.

    • User-mode targets (dumps and -remote) are driven by cdb.exe.
    • Kernel targets are driven by kd.exe.