🚀 New Release: mcp-windbg 1.5.1

2026-10-10T00:00:00+00:00

mcp-windbg 1.5.1 is out, one day after 1.5.0. Two things are new: a single mcp-windbg.exe you can download and point a client at, with no Python on the machine, and a fix for the one issue I left open in the 1.5.0 post: connecting to a debug server whose target is already running.

A Standalone mcp-windbg.exe

Until now, running the server meant Python 3.10 and pip, or uv for the Claude Code plugin. That is fine on a developer machine. It is less fine on the box where the crash actually happens: a build agent, a test VM, or a colleague's laptop with WinDbg installed and nothing else.

Every release now ships mcp-windbg.exe. It is one file, about 25 MB, with the Python interpreter and every dependency frozen in by PyInstaller. cdb.exe is still required. The debugger is the one thing the binary cannot bundle.

Download it, put it somewhere stable, and point the client at it. No args needed:

{
    "servers": {
        "mcp_windbg": {
            "type": "stdio",
            "command": "C:\\tools\\mcp-windbg.exe",
            "env": {
                "_NT_SYMBOL_PATH": "SRV*C:\\Symbols*https://msdl.microsoft.com/download/symbols"
            }
        }
    }
}

The command-line options are the same as for the Python package, so "args": ["--cdb-path", "C:\\dbg\\cdb.exe"] still works.

Two build decisions worth knowing about:

It is a one-file build. It unpacks itself into %TEMP% on every launch, which costs about a second. An MCP server starts once per session, so you pay that second once.
It is not UPX-compressed. Packed binaries get flagged by antivirus, and a debugging tool starts out suspicious enough.

Signed, With a Checksum

The executable is code signed, and each release publishes a SHA256SUMS file next to it. Both are easy to check:

(Get-FileHash .\mcp-windbg.exe -Algorithm SHA256).Hash
Get-AuthenticodeSignature .\mcp-windbg.exe | Format-List Status, SignerCertificate

Status should read Valid, and the signer is Liasoft GmbH. That is my company, and the certificate belongs to it. mcp-windbg stays a personal project, so Windows shows the company as the publisher and the file properties name me as the author. Having a certificate at hand is the only reason the binary is signed at all. Otherwise this would have been the step I skipped.

Importing Cleanly Is Not the Test

A frozen build only contains the modules PyInstaller could see. A dependency that imports lazily, or reads a data file at runtime, fails at the tool call rather than at startup. So a binary that launches and answers initialize proves very little.

The project already has an end-to-end harness that drives a real server through a real MCP client with scripted tool calls. It can now run against the binary instead of python -m mcp_windbg, with the same assertions. That happens on every pull request, and locally with scripts/Build-Exe.ps1 -Verify.

The release workflow runs the suite a second time against the signed binary. Signing rewrites the executable, and nothing had ever tested the result. The SHA256SUMS file is taken after signing for the same reason.

One limitation of the frozen build: --filter-script still works, but it only sees the parts of the standard library the bundle contains. sqlite3, xml.etree and tkinter are not in it. A filter script that needs more than that wants the pip install.

Opening a Remote Session Whose Target Is Running

This is the issue I listed under "Still Open" last week: item 2 of @xiaozhu1337's report in #130, with a fix proposed in #127. I did not ship a fix in 1.5.0 because two attempts had each broken a different case, and there was no automated test for a running remote target at all. This time the test came first.

The bug: open_cdb_remote against a debug server whose target is running never got a prompt. A running target reads no commands, so the probe the open relied on was never answered. The open waited out its whole timeout, 60 seconds by default, and then failed with Debugger initialization timed out. The session was fine.

To reproduce it, I started cdb -server tcp:port=N waitfor.exe X, typed g on the server, and attached a -remote client. The client prints its connect banner, replays the server's transcript, and then nothing. I had assumed the probe would complete without a context, as the proposed fix described. It does not. It is simply never answered.

A -remote client now starts in two phases:

Wait for the Connected to server with banner, up to the open timeout. That is where connection latency belongs. A failed connect still reports the debugger's own error, and a connect that never completes now says Timed out connecting to the debug server.
Give the target two seconds to answer the prompt probe. A stopped target answers in about 0.1 seconds on localhost. Silence means it is running, and the session opens in that state.

The initial triage then breaks in, the same way any command on a running target does after g. The result says so under Target State, and the target stays stopped until you resume it or close the session.

A wrong guess is cheap. A CTRL+BREAK sent to a target that is already stopped produces no output and leaves the session usable, so a slow connect misread as running costs nothing.

The new live scenario resumes the server's target before the open, checks the Target State line and the break banner, and makes sure the next r does not break in again. The hermetic tests cover the four startup outcomes: stopped, running, exited mid-connect, and never connected. After last week's lesson, I treat those as the floor, and the live scenario as the proof.

Upgrading

pip install -U mcp-windbg

If you use the Claude Code plugin:

/plugin marketplace update mcp-windbg
/plugin update mcp-windbg-uvx@mcp-windbg

Or skip all of that and download mcp-windbg.exe from the v1.5.1 release. Thanks again to @xiaozhu1337 for the original report. If the executable behaves differently from the Python package on your machine, I want to hear about it, so please open an issue.