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-four 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 75,547 bytes — about 19k tokens — before it has asked anything. --tools session,inspect,crash cuts that to 26,305 B for twenty 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.

Most of the tools also answer with MCP structuredContent, so a program can read a field instead of parsing prose, and a failure carries a stable category (invalid_argument, debugger, timeout, stale_session, …) rather than wording — docs/structured-results.md.

Walkthroughs

Worked sessions with the real outputs and the gotchas — the long form is in docs/walkthroughs.md.

• Crash-dump triage — a 0x9F DRIVER_POWER_STATE_FAILURE traced to nvlddmkm.sys, and a 0x13A in a driver with no PDB.
• TTD tour — opening a .run, forward/reverse navigation, and counting printf calls with symbols.
• Flare-On 12 #8 — a full TTD → Z3 solve of an obfuscated Qt crackme.
• Driver IOCTL surface — recovering a dispatch switch on a live KDNET kernel and deciding user-mode reachability.
• Explorer won't start — the server debugging its own host: a dead Windows shell traced through three faults to a malformed State Repository.
• Disassembler coordinates — joining a crash_triage frame to a function in an image fetched on another machine.

Driving it — hosted or local, here or on another machine

Anything that speaks MCP can hold this server, and DbgEng is the only part pinned to Windows. So the model may be a hosted one inside an editor, a local one in ollama, or an ollama cloud model, and it does not have to run on the machine being debugged.

One machine needs no configuration at all: the client launches the binary and talks to it over stdio, which is the Quick start above.

Two machines need a listener. For a session you are driving anyway, run it in the foreground on the Windows host — this works wherever the binary happens to live:

$env:WINDBG_MCP_LISTEN_TOKEN = "<a long random string>"   # this shell only
windbg-mcp.exe --listen 127.0.0.1:8765

For anything longer-lived, install it as a service — from a protected directory. The SCM stores that exact path for a LocalSystem auto-start service, so whoever can write the directory, or drop an engine DLL beside the exe, gets their code run as SYSTEM at the next start. --install-service therefore refuses an exe outside %ProgramFiles%, %ProgramFiles(x86)% or %SystemRoot% — which a downloaded zip, a Scoop shim or a target\release build all are — so move the whole deployment first: the exe, the engine DLLs beside it, and x86\. Then, elevated:

$env:WINDBG_MCP_LISTEN_TOKEN = "<a long random string>"   # this shell only
& "$env:ProgramFiles\windbg-mcp\windbg-mcp.exe" --install-service --listen 127.0.0.1:8765
Start-Service windbg-mcp          # --install-service only *registers* it

On a machine that is entirely yours, --allow-unprotected-path says so out loud and installs in place; that is a development install, not a deployment.

Either way, from the machine you are actually working on, for as long as you want the link:

ssh -N -L 8765:127.0.0.1:8765 <windows-host>

The listener refuses to start without a token, because it serves execute, launch and debug_batch — an open port here is arbitrary code on the host holding your kernel debugger. Bind loopback and forward over ssh rather than exposing it. Each client authenticates as itself, and can be served a narrower --tools surface than the run's default, which is how a local model and an editor share one listener without sharing sessions. docs/remote-listener.md is the operator's reference.

Pointing ollama at it is the client's job, not this server's. An MCP client that drives an ollama model holds the listener exactly as an editor does — nothing here has to be installed, and this server never learns which kind of model answered. ollama ships integrations for a number of those clients; ollama launch lists them, and ollama launch claude --model <tag> is one. A local tag and an ollama cloud tag are the same route, differing only in the model name.

docs/local-model.md is the runbook: the arrangements, choosing a model that can actually run, which of two clocks a quiet model loses its sessions to, and what a cloud tag can no longer tell you about its own run.

Whether a local model copes — the benchmark

The tool surface is paid on every turn, so "can a model that runs on a laptop actually drive this?" is a question about this server as much as about the model. The repo ships the benchmark rather than the assertion: tools/local_model_eval.py runs a grid of model × tool surface × context window, tools/bench_listener.ps1 serves all three surfaces from one listener as three separately-budgeted clients, and the answer key is read off the checked-in crash dumps with this server's own tools before any model sees them. Claude is in the grid as the control, not as a competitor. docs/local-model-eval.md is the write-up.

Running the grid yourself needs a development environment rather than a release: the release zip is windbg-mcp.exe, the x86\ worker and LICENSE, so tools/ comes from a checkout, and the driver and grader are Python 3. Nothing above this section needs either — driving the server with a local model is a client's job, and the driver here exists to measure that, one task list at a time, with no interactive mode. agent-sandbox-vm is the Hyper-V / Parallels VM setup this project is developed and benchmarked in.

• The context window was not the binding constraint — on that bench's runtime, which is the qualifier that matters. A 17,300-token surface answered all six tasks at a served 8,192-token window, multi-turn ones carrying 10,000 characters of tool output included. The arithmetic that predicted otherwise is in docs/local-model.md, and it was wrong; ask ollama ps what your own runtime serves rather than generalising either result.
• Cutting 51 tools to 11 costs two of six answers — the surface that grid measured, before the three asynchronous-execution tools. Most facts here are reachable by more than one route, so a narrow surface keeps the ones that matter.
• It measures this server before it measures the model. Every off-surface tool call the first grid recorded was a name this server had advertised and would then refuse — in the instructions sent at connect time, and in the descriptions of the tools it does serve. Both are narrowed per client now, and re-running the narrow cells took those calls from 17 to 6, with every server-taught name at zero.

The Tool Surface Grid is the visual write-up — 33 cells, five models, the three axes, and what the two fixes it produced did and did not buy.

Limitations

The full list, with what each one means for a workflow, is in docs/limitations.md. The four that catch people first:

• TTD is user-mode only — a Microsoft limitation, so a kernel target cannot be time-travelled.
• One command at a time per session. Sessions run concurrently, but each is one engine running operations serially: await each result before sending the next call against that session.
• Symbol names need setup on the debugger host — msdia140.dll beside the binary, a symbol path, and (for TTD) a reload at a stopped position. Without them, address-based queries still work.
• The pool and heap walkers need a stopped x64 target. They decode x64 allocator structures, so a 32-bit target has no heap_* tools whichever worker holds it — SOS's own !dumpheap/!eeheap are the managed equivalent, and reaching those is what the 32-bit worker and its x86\ engine payload (docs/install.md) are for.