Command-line options¶

The server is started by your MCP client, but the same options apply when you run it by hand:

python -m mcp_windbg --help

The mcp-windbg entry point is equivalent, if its scripts directory is on your PATH.

All options¶

Option	Default	Description
`--transport {stdio,streamable-http}`	`stdio`	Transport protocol. See Transports.
`--host HOST`	`127.0.0.1`	Host to bind for the HTTP transport.
`--port PORT`	`8000`	Port to bind for the HTTP transport.
`--cdb-path PATH`	auto-detect	Full path to `cdb.exe`. See Symbols and CDB.
`--kd-path PATH`	auto-detect	Full path to `kd.exe`, used for kernel debugging. See Symbols and CDB.
`--symbols-path PATH`	`_NT_SYMBOL_PATH`	Symbol search path used when opening a session.
`--no-dump-dir-symbols`	off	Do not auto-add a dump's own directory to the symbol path.
`--filter-script PATH`	none	Python script with tool-text hooks. See Filter script hooks.
`--timeout SECONDS`	`60`	Baseline command/connect timeout; a floor for the per-tool defaults.
`--verbose`	off	Verbose logging to stderr.

General¶

--timeout sets the baseline command/connect timeout and acts as a floor for the per-tool defaults (open_cdb_dump 180s, run_cdb_command 60s, run_kd_command 120s). Any open_*/run_* call can also override it per call with timeout_seconds. Raise the floor for heavy analysis on large dumps, for example --timeout 120.
--verbose logs to stderr, which is safe under stdio (stdout is the MCP transport).

Transports¶

Transport	Use it for
`stdio` (default)	Local MCP clients that launch the server as a child process: VS Code, Claude Desktop, Copilot CLI.
`streamable-http`	Running the server separately and connecting over HTTP.

Standard I/O (default):

mcp-windbg
# equivalently
mcp-windbg --transport stdio

Streamable HTTP:

mcp-windbg --transport streamable-http --host 127.0.0.1 --port 8000

The endpoint is then http://127.0.0.1:8000/mcp. See Client configuration for the matching client snippet and Debug from another machine for the full workflow.

The HTTP transport has no authentication

Anyone who can reach the port can drive cdb.exe on the host. Keep --host 127.0.0.1, or expose it only on a trusted network or behind an SSH tunnel or authenticating proxy.

Symbols and CDB¶

--cdb-path - the server auto-detects cdb.exe in the common Windows Kits and Microsoft Store locations. Set this when yours is installed elsewhere.
--kd-path - the same, for the kd.exe used by open_kd_session. Kernel debugging needs kd.exe; cdb.exe cannot drive a kernel connection, so this is a separate option from --cdb-path.
--symbols-path - sets the symbol search path for new sessions. If omitted, the debugger uses _NT_SYMBOL_PATH from the environment, which is the usual way to configure the Microsoft symbol server (see Getting started).
Dump directory symbols - when a session is created for a dump, the server prepends the dump's own directory to the symbol path so co-located .pdb files are found. Disable this with --no-dump-dir-symbols.

Per-call symbol paths are also available on the open_* tools, see open_cdb_dump and open_cdb_remote.

Filter script hooks¶

Use --filter-script to load a small Python helper that rewrites tool text only, for example to redact PII before it leaves the machine. The script never sees the full MCP JSON-RPC envelope, which keeps the hook surface small and avoids protocol interference. It runs in-process with the server, so treat it as trusted code.

The script may define either or both of these functions:

def process_input(text, context):
    return text


def process_output(text, context):
    return text

process_input is applied to string-valued tool arguments before the tool runs.
process_output is applied to TextContent.text values returned by tools before they go back to the client.
text is always a plain str.
context includes hook, tool_name, transport, and call_id.
Input callbacks also receive argument_path such as $.command or $.payload.notes[0].
Output callbacks also receive content_index for the returned text item.
call_id is stable for the lifetime of one tool invocation, so input and output for the same call can be correlated.
A hook may return None to leave the text unchanged, or a replacement string.

Example redaction filter:

def process_input(text, context):
    if context["tool_name"] == "run_cdb_command" and context["argument_path"] == "$.command":
        return text.replace("user@example.com", "[redacted-email]")
    return text


def process_output(text, context):
    return text.replace("user@example.com", "[redacted-email]")

Start the server with the filter enabled:

mcp-windbg --filter-script C:\filters\pii_redaction.py