WindDbg MCP

This MCP (Model Context Protocol) server enables a WinDbg GUI workflow by connecting a Python-based MCP server to WinDbg through a PyKD plugin. It provides a JSON‑RPC bridge that lets you query debugger state, run commands, analyze memory and exceptions, and retrieve thread/module information from WinDbg in a streamlined, scriptable way.

How to use

You use the Windbg GUI MCP Server by running the MCP backend locally and connecting a client with MCP capabilities. The server exposes a HTTP endpoint you can reach from your MCP client, and it translates your requests into WinDbg operations via the PyKD integration.

How to install

Prerequisites: You need a Windows operating system, WinDbg (included with Windows SDK or Windows Store), Python 3.11 or newer, and PyKD installed in the Python environment used by WinDbg.

pip install pykd

# Or download and install from the official PyKD releases page.
# Then install the Windbg GUI MCP server in development mode from its directory.
cd windbg-gui-mcp
pip install -e .

Configuration & runtime configuration

Once the server is started, the WinDbg GUI MCP Server announces the HTTP endpoint for JSON‑RPC communication. You should see a message similar to the following indicating the server is listening at the local URL.

[WinDbg MCP] Server started at http://localhost:13338

Load the MCP plugin in WinDbg

In WinDbg, load the PyKD extension and then load the MCP plugin to establish the bridge to the Python backend.

.load pykd
!py C:\path\to\windbg-gui-mcp\src\windbg_gui_mcp\windbg_plugin.py

Accessing tools via the MCP server

You can execute a variety of operations through the MCP client to interrogate and manipulate the target from WinDbg through the server. The MCP server exposes convenient tools for connection checks, debugger information, command execution, stack traces, registers, modules, memory reads, exception analysis, and thread information.

# Example patterns (use your MCP client to call these operations):
# check_connection
# get_debugger_info
# execute_command("kv")
# get_stack_trace
# get_registers
# get_modules
# read_memory(address, size)
# analyze_exception
# get_threads

Advanced usage and customization

You can extend the MCP server with custom JSON‑RPC methods inside the windbg_plugin.py file. Define a new command, then expose it via an MCP tool so your client can call it as a new operation.

@jsonrpc
def my_custom_command(param: Annotated[str, "Description"]) -> str:
    """My custom WinDbg command"""
    result = pykd.dbgCommand(f"!myext.mycmd {param}")
    return result

@mcp.tool()
def my_custom_command(param: str) -> str:
    """My custom WinDbg command"""
    return make_jsonrpc_request("my_custom_command", param)

Troubleshooting

If you cannot connect to the WinDbg server or encounter import errors, verify that PyKD is properly loaded in the WinDbg Python environment and that the MCP server process is running. Also check for port conflicts on 13338.

# Verify PyKD is loaded in WinDbg's Python environment
!py import sys; print(sys.version)

# Check server availability from your MCP client
# If needed, test connectivity to http://localhost:13338

# Check for port usage on Windows
netstat -ano | findstr 13338

Development

To run tests or build and verify the MCP server locally, use the standard Python tooling described here. You can run tests with pytest and generate runtime configurations as needed.

pytest tests/

python -m windbg_gui_mcp --config

Available tools

check_connection

Checks the current connection status between WinDbg and the MCP server.

get_debugger_info

Retrieves debugger details such as kernel/user mode, architecture, and associated metadata.

execute_command

Executes a specified WinDbg command through the MCP bridge.

get_stack_trace

Fetches the current call stack from the debuggee.

get_registers

Returns all CPU register values from the active thread.

get_modules

Lists the modules currently loaded in the debug session.

read_memory

Reads a block of memory from a given address for a specified size.

analyze_exception

Runs a full exception analysis using a detailed debugger report.

get_threads

Provides information on all threads in the debug session.