Windbg MCP

windbg-mcp

An MCP server that exposes WinDbg/DbgEng to AI agents (Claude Code, Claude Desktop, Cursor, …) — over stdio, or over HTTP with --listen, which serves the same tools to clients that are not on the machine DbgEng runs on. It drives a live debugger engine for user-mode, kernel-mode, crash-dump, and Time Travel Debugging (TTD) workflows — and reads a VBS guest's Secure Kernel (VTL1) out of a Hyper-V checkpoint or controls selected VPs in an exact disposable VBS VM through built-in h3probe providers (or operator-supplied protocol providers). Driver source is included; driver binaries, signing, installation and service lifecycle remain operator-owned.

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.

Official sources

This repository — [`github.com/glslang/windbg-mcp`](https://github.com/glslang/windbg-mcp) — is the project's only official home. If you are reading this anywhere else, you are reading a copy: a mirror can carry this README word for word, so the address it is served from is the check, not what it says.

It is published through these channels and no others:

• Source: this repository, and glslang/dbgscope for the engine bindings.
• Binaries: this repository's releases — a zip and an .mcpb bundle, both listed in SHA256SUMS.txt and both covered by a signed build-provenance attestation.
• MCP registry: io.github.glslang/windbg-mcp in the official registry, whose io.github.glslang namespace only this GitHub account can publish to. The entry points at the .mcpb above.
• Claude Code plugin: /plugin marketplace add glslang/windbg-mcp — the marketplace is this repository.

The Scoop bucket is community-maintained and outside this project; that section says what trusting it involves.

MCP directories and marketplaces list public repositories without asking. None of them is affiliated with this project or acts for it, so before using windbg-mcp from one:

• It is free, and there is no paid edition. It is MIT-licensed, with no subscription, licence key or premium tier. A listing that charges for it is not a channel of this project, and the money does not reach it.
• There is no hosted version. The server drives DbgEng on the Windows machine it runs on, against targets that machine can reach, so it belongs on yours or on one you control — --listen exists to serve *your* clients. An endpoint offering it as a service is running someone else's code, and your agent would be sending it what you debug: dumps, memory, traces.
• A binary from anywhere else is a debugger you have not vetted. This one runs elevated — a kernel attach and TTD recording need Administrator, and --install-service runs it as LocalSystem — and it reads and writes other processes and the kernel. A tampered build in that seat owns the machine and every target it reaches. Take binaries from the releases above and check them before running them: the hash against SHA256SUMS.txt, and the provenance with

  gh attestation verify <file> --repo glslang/windbg-mcp `

--signer-workflow glslang/windbg-mcp/.github/workflows/release.yml

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, driving it with Apple's on-device model, disassembler coordinates, smoke test, token budget, releasing.

Secure Kernel (VTL1) has five routes. The opt-in securekernel group contains four tools for a fixed capture, eleven tools for selected-VP live control, the managed KD facade, two tools that trace VTL0 secure-service entries in an ordinary kernel session, and two tools for a separate hypervisor transition trace; the session contracts are in docs/sessions.md. The separate --sk-live command-line role decodes a running guest without controlling it, and the --sk-kd-target role puts an installed WinDbg in front of the live-control session over a local named pipe, within the limits docs/secure-kernel/kd-facade.md records. Live decode, live control and the facade include h3probe child providers; the operator supplies the built, signed, installed and running driver. Custom protocol providers remain supported. The VTL0 trace and guest harness are documented in docs/secure-kernel/vtl0-call-trace.md; the intervening hypervisor trace is in docs/secure-kernel/hypervisor-transition-trace.md. The evidence, controls and dead ends are recorded gate by gate.

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 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

Eighty-nine tools in nine --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.

| Server | session | server_log — the s