Troubleshooting

Common problems and fixes. If none of these help, enable verbose logging and open a GitHub issue with the details.

Tools do not appear in the client

Confirm MCP is enabled in the client (in VS Code: settings -> MCP -> enable in Copilot Chat) and restart it.
Check that the config file is valid JSON and in the right place, see Client configuration.
In VS Code, check Output -> Model Context Protocol for startup errors.
Verify the server runs at all:
```
python -m mcp_windbg --help
```

CDB not found

The server auto-detects cdb.exe, but cannot if it is installed somewhere unusual.

Confirm it is reachable: cdb.exe -version.
Install Debugging Tools for Windows (WinDbg from the Microsoft Store, or the Windows SDK).

Point the server at it explicitly with --cdb-path:

"args": ["--from", "git+https://github.com/svnscha/mcp-windbg", "mcp-windbg",
         "--cdb-path", "C:\\Program Files (x86)\\Windows Kits\\10\\Debuggers\\x64\\cdb.exe"]

Symbols do not load

Stack traces full of offsets and no function names mean symbols are not resolving.

Set _NT_SYMBOL_PATH in the client env, see Getting started:

"env": {"_NT_SYMBOL_PATH": "SRV*C:\\Symbols*https://msdl.microsoft.com/download/symbols"}

For your own binaries, keep the matching .pdb next to the dump (the dump's directory is added automatically) or pass an extra path, see Symbols and CDB.
Confirm the machine can reach https://msdl.microsoft.com.

Command timeouts

A command that exceeds the per-command limit reports a timeout.

Raise it with --timeout, for example --timeout 120.
On large dumps, prefer targeted commands over broad analysis.
The timeout error includes the output read before CDB stopped responding. If the command produces more than the diagnostic limit, the response ends with a truncation note; increase the timeout or inspect the target directly for the complete output.

Module not found (pip installs)

No module named 'mcp_windbg' from a pip-based config:

Verify the install: pip list | findstr mcp-windbg.
For a virtual environment, point command at that interpreter, for example ${workspaceFolder}/.venv/Scripts/python.

Remote debugging issues

Cannot connect to a remote target:

Use a supported connection string format, for example tcp:Port=5005,Server=192.168.0.100.
Check network reachability to the target and that the debugging server is listening.
Check the target's firewall.
Timed out connecting to the debug server means the client reached neither the server nor an error within the timeout, which points at the network rather than the target. A refused connection fails fast with DebugConnect failed, and a target that is merely running is not a connect failure: the open breaks into it.
open_cdb_remote is user-mode only (-remote). For kernel targets (-k) use open_kd_session, see Debug a kernel target. A kernel connect that times out with no_debuggee means the target isn't transmitting or another debugger already holds the (point-to-point) connection.

HTTP transport will not connect

Using the streamable-http transport and the client cannot reach the server:

The endpoint includes the /mcp path, for example http://host:8000/mcp.
The server binds 127.0.0.1 by default. To reach it from another machine, start it with --host 0.0.0.0 and open the port in the host firewall.
There is no authentication, so keep it on localhost or a trusted network, see Debug from another machine.

Filter script stops the server from starting

A --filter-script that fails to load:

The script must define process_input and/or process_output; a file with neither is rejected. Check the path and that the file is valid Python.
Startup errors appear in the client's MCP output (in VS Code, Output -> Model Context Protocol).
A hook that raises at runtime is reported as a tool error, not a crash; check its logic.

Server crashes when run directly in a terminal

mcp-windbg speaks MCP over stdin/stdout; it is meant to be launched by a client, not typed into interactively. Run it through your MCP client, or with --help to see options.

Diagnostics

Enable verbose logging (goes to stderr, safe under stdio):

"args": ["--from", "git+https://github.com/svnscha/mcp-windbg", "mcp-windbg", "--verbose"]

Check the basics:

cdb.exe -version
python -m mcp_windbg --help

4.8 KiB Raw Permalink Blame History