windbg-mcp

An MCP server that exposes WinDbg/DbgEng to AI agents (Claude Code, Claude Desktop, Cursor, …) over stdio. It drives a live debugger engine for user-mode, kernel-mode, crash-dump, and Time Travel Debugging (TTD) workflows.

The low-level engine bindings live in dbgscope (src/dbgeng.rs); this crate adds process-per-session engine supervision and the rmcp tool surface on top.

Documentation

This file is the map. Each topic is one document, and each document is the whole of that topic.

Operator and reference material: remote listener, driving it with ollama, disassembler coordinates, smoke test, token budget, releasing.

Quick start

Windows x64, with dbgeng.dll from System32 — enough for live user-mode, kernel and crash-dump work. TTD .run replay, !analyze and the driver tools each need files that engine does not ship; docs/install.md is the one-time copy.

Download a prebuilt windbg-mcp-vX.Y.Z-windows-x64.zip from a release, or build it:

cargo build --release

Then point a client at the binary:

// .mcp.json  (or claude_desktop_config.json under "mcpServers")
{
  "mcpServers": {
    "windbg": {
      "command": "C:\\workspace\\windbg-mcp\\target\\release\\windbg-mcp.exe"
    }
  }
}

The client and the model do not have to run where DbgEng does: --listen <addr> serves the same tools over HTTP, one bearer token per client, so a Mac can drive a Windows VM — and the model itself can be a local one. Driving it below has the configurations.

cargo test covers the unit tests plus an end-to-end smoke test that drives the built binary over stdio; run it after a dependency bump or an MCP spec revision — docs/smoke-test.md.

How it works

One debug session per process. dbgeng.dll holds a single debuggee session per process, so this server runs the MCP protocol in a supervisor and each open target in its own engine worker child process. Two things follow: a session that cannot be unwound — a live-kernel attach waiting on a guest that never dials in — costs a process rather than the server, and sessions are concurrent (triage a crash dump while a kernel attach is live, up to four at once).

Every tool that touches a target takes the session_id an opener returned, and that is what routes the call. Omit it and the call goes to the current session. docs/architecture.md has the process model and the file-by-file breakdown; docs/sessions.md has the handle rules, the cap, and what to do when a session is stuck.

A 32-bit target gets a 32-bit worker. An extension DLL is loaded into the debugger's own process, so .NET's SOS on a 32-bit target is reachable only from a 32-bit host — which a process cannot become after its image has loaded. So the release ships a second build of this same server at x86\windbg-mcp.exe, and a 32-bit dump or a WoW64 attach_process is opened by that worker instead of by a re-execution of the x64 one. A client cannot tell: one server, one handle, one tool surface. Where that worker or its 32-bit engine is absent the target still opens on the x64 build — native analysis of it works and always has — and says so in the opener's limitation.

Tools

Fifty-seven tools in eight --tools groups; the rows below split some of those groups by theme. The --tools column is the name that selects one — see Serving fewer tools.

All of them are served unless you say otherwise, and the definitions cost the model 80,579 bytes — about 20k tokens — before it has asked anything (measured 2026-09-05). --tools session,inspect,crash cuts that to 29,744 B for twenty-two tools, and a --listen client can be given a narrower surface than the run's default. docs/tool-surface.md has the arithmetic, the rule that session is always included, and what a typed operand may not contain.