windbg-inproc-mcp

MCP servers for WinDbg kernel and user-mode debugging — in-process HTTP MCP in WinDbg plus an optional Python sidecar on the debug VM.

Topics: windbg · mcp · cursor · kernel-debugging

The Host runs a C++ WinDbg extension with in-process HTTP MCP; an optional Target Python sidecar runs on the debugged VM for local shell, sc.exe, and driver file operations.

Host (dev machine)                    Target VM (optional)
┌─────────────┐                         ┌──────────────────┐
│   Cursor    │── HTTP :60000+/mcp ──►│ WinDbg + DLL     │  breakpoints, memory, g
│             │                         └────────┬─────────┘
│             │── HTTP :60100/mcp ─────────────►│ target_mcp.py  │  sc, shell, copy .sys
└─────────────┘                         └──────────────────┘

• Prerequisites
• Cursor configuration
• Part 1 — windbgInprocMcp.dll (C++ extension)
• Part 2 — target_mcp (Python sidecar)
• Repository layout
• Security
• License

Building the DLL: The linker must find dbgeng.lib (Debugger Engine). Install Debugging Tools for Windows (WinDbg / SDK debugger components) and ensure the Windows SDK is on your machine—the same SDK that ships with Visual Studio is usually enough. If MSBuild fails with cannot open file 'dbgeng.lib', install or repair the Windows SDK and Debugging Tools, then rebuild.

Both components use HTTP MCP on a lab network only (no TLS). Do not expose to the public internet.

The Host MCP port is not fixed at 60000. On load, the extension tries 60000, then 60001 … 60999 until it finds a free port (so multiple WinDbg instances can each host MCP). Always confirm the actual URL before editing Cursor config.

Find the Host port

1. After .load, read WinDbg output, e.g. HTTP MCP server started at: http://127.0.0.1:60001/mcp
2. Or in WinDbg: mcphttpstatus
3. Or call the MCP tool debug_session — the Endpoint: / Port: lines show the live URL

Then set that URL in ~/.cursor/mcp.json. Example with both servers (replace <host-port> with the value from step 1–3):

{
  "mcpServers": {
    "windbg-inproc-mcp": {
      "url": "http://127.0.0.1:<host-port>/mcp",
      "timeout": 30000
    },
    "target": {
      "url": "http://<vm-ip>:60100/mcp",
      "headers": {
        "Authorization": "Bearer <token-from-target-vm>"
      }
    }
  }
}

Add the Host entry manually to ~/.cursor/mcp.json, then restart Cursor. If Cursor cannot connect after opening a second WinDbg, run mcphttpstatus in each session and point each MCP client entry at the matching port.

Install the Target entry from the Host (replace VM IP and Windows username):

python target_mcp\install_target_cursor_config.py --host 192.168.x.x --user <vm-windows-user>

On the Target VM, print the auth token:

python target_mcp.py --show-token

In-process HTTP MCP inside WinDbg. MCP clients connect directly to the extension DLL—no Python bridge or named pipe.

Requires Visual Studio 2017 or later with the Desktop development with C++ workload (Community, Professional, Enterprise, or Build Tools), plus a Windows SDK with debugger libraries (dbgeng.lib). Install Debugging Tools for Windows if the link step cannot find dbgeng.lib. The script uses vswhere when available, otherwise scans common install paths.

extension\build_vs2017.bat

Output: extension\build\x64\Release\windbgInprocMcp.dll

.load C:\path\to\windbg-inproc-mcp\extension\build\x64\Release\windbgInprocMcp.dll

HTTP MCP starts automatically. The extension binds the first free port in 60000–60999 (default attempt: 60000). WinDbg prints the URL on load; use mcphttpstatus anytime to see it again. Put that URL in Cursor — not a guessed port.

mcphttpstatus

Example output: HTTP MCP server is running at: http://127.0.0.1:60001/mcp (port 60001)

Runs on the debugged VM. Complements the Host DLL; it does not replace WinDbg debugging.

cd target_mcp
pip install -r requirements.txt

python target_mcp.py

Or:

start_target_mcp.bat

• Listens on http://0.0.0.0:60100/mcp by default
• Requests UAC elevation if not already admin
• Prints windows_user, IPv4 addresses, and a stable Bearer token (derived from the VM username)
• Log file: target_mcp.log in the target_mcp directory (truncated on each restart)

manage_driver example:

manage_driver(action="status", name="MyDriver")
manage_driver(action="stop", name="MyDriver")
manage_driver(action="install", name="MyDriver", source_sys_path="C:\path\to\MyDriver.sys")

run_sequence example:

[
  {"type": "sc", "action": "stop", "service_name": "MyDriver"},
  {"type": "cmd", "command": "echo done"}
]

When the Target is broken into the kernel debugger, the whole VM is frozen and this HTTP server will not respond. Resume the Target first:

1. windbg-inproc-mcp: break_debugger     (or already broken in)
2. windbg-inproc-mcp: run_command("g")   (Target runs)
3. target: sc_control(action="stop", service_name="MyDriver")
4. windbg-inproc-mcp: break_debugger     (break again to continue debugging)

Bearer token is deterministically derived from the Target VM %USERNAME% (HMAC-SHA256). It is stable across restarts; no TARGET_MCP_TOKEN environment variable.

When configuring Cursor on the Host, --user must be the VM Windows username, not the Host username.

copy_file / read_file allow only:

• C:\Windows\System32\drivers
• C:\Windows\Temp and %TEMP%
• The target_mcp directory
• Paths listed in TARGET_MCP_ALLOWED_PATHS

manage_driver can read a source .sys from any existing path; the install target is always System32\drivers.

If the Host cannot connect, allow inbound TCP on the Target (run as Administrator):

netsh advfirewall firewall add rule name="Target MCP" dir=in action=allow protocol=TCP localport=60100

windbg-inproc-mcp/
├── extension/                    # C++ WinDbg extension (windbgInprocMcp.dll)
├── target_mcp/                   # Python sidecar for the debugged VM
│   ├── target_mcp.py             # Entry point
│   ├── start_target_mcp.bat
│   ├── install_target_cursor_config.py
│   └── tools.py, executor.py, security.py, ...
├── LICENSE
└── README.md

• Lab / debug network only. HTTP without TLS; Bearer tokens are not suitable for untrusted networks.
• Target MCP requires Administrator privileges and can run shell commands and service control.
• Command blocklists reduce accidental damage (e.g. format, shutdown /p); they are not a sandbox.
• Never bind Target MCP to a public interface or expose it outside your debug VLAN.

See LICENSE.