Skip to main content
Glama

CDB-MCP: CDB Debugger MCP Server

English | 中文

Exposes Microsoft CDB (Console Debugger) capabilities through the Model Context Protocol (MCP), enabling LLMs to perform live debugging, dump analysis, remote debugging, and more.

Design Philosophy

The server is a transport layer between the LLM and cdb.exe, not an abstraction layer for CDB commands.

The LLM already has knowledge of CDB/WinDbg commands. The server only does three things:

  1. Manage cdb.exe subprocesses (start/stop/list sessions)

  2. Forward commands and output (LLM sends CDB command string -> forwarded to cdb.exe -> raw text output returned)

  3. Provide Ctrl+Break interrupt (cannot be done via stdin text; requires an OS signal)

It does not wrap specific CDB commands, does not parse output into JSON, and does not restrict command syntax.

Related MCP server: dump-analyzer-mcp-server

Tools

Tool

Description

create_session

Start cdb.exe (launch / attach / dump / remote)

close_session

Close or detach a session

list_sessions

List active sessions

execute

Send a CDB command string; returns status (completed/pending/error) and output

get_output

Poll the output buffer of the current pending command (sends no command)

wait_for_prompt

Wait for the current pending command to complete

interrupt

Send Ctrl+Break to interrupt the running target

Prerequisites

  1. Windows Debugging Tools -- provides cdb.exe

    • Install via Windows SDK: select "Debugging Tools for Windows"

    • Or install WinDbg Preview from Microsoft Store

    • Common path: C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\cdb.exe

  2. Python 3.11+ and uv

Installation

git clone https://github.com/cc682/cdb-mcp.git cdb-mcp
cd cdb-mcp

# Create virtual environment and install dependencies
uv venv --python 3.12 .venv
uv sync

MCP Client Configuration

VS Code Copilot

Create .vscode/mcp.json in the project root:

{
  "servers": {
    "cdb-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:\\path\\to\\cdb-mcp",
        "python",
        "-m",
        "cdb_mcp"
      ],
      "env": {
        "CDB_MCP_CDB_PATH": "C:\\Program Files (x86)\\Windows Kits\\10\\Debuggers\\x64\\cdb.exe",
        "CDB_MCP_SYMBOLS_PATH": "srv*C:\\symbols*https://msdl.microsoft.com/download/symbols"
      }
    }
  }
}

Claude Desktop

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "cdb-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:\\path\\to\\cdb-mcp",
        "python",
        "-m",
        "cdb_mcp"
      ],
      "env": {
        "CDB_MCP_CDB_PATH": "C:\\Program Files (x86)\\Windows Kits\\10\\Debuggers\\x64\\cdb.exe",
        "CDB_MCP_SYMBOLS_PATH": "srv*C:\\symbols*https://msdl.microsoft.com/download/symbols"
      }
    }
  }
}

Replace C:\\path\\to\\cdb-mcp with the actual project path.

Environment Variables

Variable

Description

Default

CDB_MCP_CDB_PATH

Full path to cdb.exe

Auto-discovered

CDB_MCP_SYMBOLS_PATH

Symbol path (semicolon-separated)

Microsoft symbol server

CDB_MCP_SOURCE_PATH

Source code path

Empty

CDB_MCP_MAX_SESSIONS

Max concurrent sessions

4

CDB_MCP_CMD_TIMEOUT

Default command timeout (seconds)

30

CDB_MCP_OUTPUT_BUFFER

Output buffer line count

1000

Symbol path format: srv*local_cache_dir*symbol_server;extra_path1;extra_path2

When debugging your own program, add the directory containing your PDB:

srv*C:\symbols*https://msdl.microsoft.com/download/symbols;C:\MyProject\bin

Verification

After configuration, reload the VS Code window (Ctrl+Shift+P -> Developer: Reload Window). Type /tools in chat to see the 7 cdb-mcp tools.

If tools are disabled, set their status to Allow in the /tools panel.

Usage Examples

Dump Analysis

1. create_session(type="dump", target="C:\dumps\crash.dmp")
   -> returns session_id

2. execute(command="!analyze -v", timeout=600)
   -> {"status": "completed", "output": "analysis results..."}

3. execute(command="k")
   -> {"status": "completed", "output": "call stack..."}

4. execute(command="lm")
   -> returns module list

5. close_session()

Live Debugging (Breakpoints)

1. create_session(type="live_launch", target="C:\app\myapp.exe")
2. execute(command="bp myapp!main")     -> set breakpoint
3. execute(command="g")                  -> {"status": "completed"} breakpoint hit
4. execute(command="k")                  -> view call stack
5. execute(command="dv")                 -> view local variables
6. execute(command="p")                  -> single step
7. close_session()

Long-Running Commands (Pending Polling)

1. execute(command="g", timeout=2)
   -> {"status": "pending", "output": "program starting..."}

2. get_output()                          -> poll, no command sent
   -> {"status": "pending", "output": "tick 1\ntick 2\n...", "command": "g"}

3. get_output()                          -> keep polling
   -> {"status": "pending", "output": "tick 1-10\n...", "command": "g"}

4. interrupt()                           -> interrupt the running target
   -> {"status": "interrupted"}

5. wait_for_prompt(timeout=10)           -> wait for prompt
   -> {"status": "completed", "output": "post-interrupt output..."}

6. execute(command="k")                  -> session recovered
   -> {"status": "completed", "output": "call stack..."}

Tech Stack

  • Language: Python 3.11+

  • MCP SDK: mcp 2.0 (official Python SDK)

  • Debug backend: cdb.exe (Windows Debugging Tools)

  • Package manager: uv / pip

  • Testing: pytest

License

MIT

Available Tools

7 tools
close_sessionA

Close a debug session, terminating the cdb.exe subprocess.

With detach=true the debugger detaches (target process keeps running). With detach=false the session is closed directly.

Inputs: detach, session_id. Returns: result

create_sessionA

Create a CDB debug session by launching a cdb.exe subprocess.

Four session types:

  • live_launch: launch a new process under the debugger (target=exe path, args=launch args)

  • live_attach: attach to a running process (target=PID)

  • dump: load a dump file (target=dump file path)

  • remote: connect to a remote debug server (target=connection string)

After creation, use the execute tool to send CDB commands.

Inputs: type (required), target (required), args, image_path, +3 more. Returns: result

executeA

Send a CDB command to the current debug session. Returns status and output.

This is the core tool for interacting with CDB. The LLM constructs valid CDB command strings; the server forwards them to cdb.exe.

Returns JSON: {"status": "completed", "output": "..."} -- command finished {"status": "pending", "output": "..."} -- command timed out but still running {"status": "error", "output": "", "error": "..."} -- error occurred

When status is "pending":

  • The command is still running in CDB (not interrupted)

  • Use get_output() to poll for more output

  • Use interrupt() to interrupt the command

  • Use wait_for_prompt() to wait for completion

Common commands:

  • g : continue execution (often returns pending; use interrupt to stop)

  • t / p / gu : step into / step over / step out

  • bp / bc / bl : set / remove / list breakpoints

  • r : display registers

  • k : display call stack

  • ~ : list threads

  • lm : list modules

  • dv : display local variables

  • ?? expr : evaluate expression

  • u addr : disassemble

  • d addr L n : read memory

  • !analyze -v : automatic crash analysis (slow; use large timeout)

Note: q/qq/qd commands are blocked (use close_session instead).

Inputs: command (required), timeout, session_id. Returns: result

get_outputA

Get the output status and content of the current command.

Used to poll a command's progress after execute() returns pending. Does not send any command to CDB; only reads the existing output buffer.

Returns JSON: {"status": "pending", "output": "...", "command": "g"} -- command still running; output is what has been produced so far {"status": "idle", "output": "", "command": null} -- no command is executing

Typical usage:

  1. execute("g") -> returns pending

  2. get_output() -> check for new output (e.g. breakpoint hit info)

  3. If output shows breakpoint reached, call interrupt() to stop

  4. If still running, keep polling with get_output()

Inputs: session_id. Returns: result

interruptA

Interrupt the running debug target (send Ctrl+Break).

Used after execute('g') returns pending, to stop the target. CDB will stop the target and display a new prompt. After interrupt, use get_output() to see the post-interrupt output.

Inputs: session_id. Returns: result

list_sessionsA

List all active debug sessions and their states.

Inputs: no named parameters. Returns: result

wait_for_promptA

Wait for the current pending command to complete (CDB prompt to appear).

Used after execute() returns pending, to continue waiting for command completion. If no command is pending, returns idle status.

Returns JSON: {"status": "completed", "output": "..."} -- command finished {"status": "pending", "output": "..."} -- still running, timed out again {"status": "idle", "output": ""} -- no command is executing

Inputs: timeout, session_id. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: session lifecycle (create/close/list), command execution, output polling, waiting, and interrupting. Even the similar get_output and wait_for_prompt are differentiated by their descriptions (reading buffer vs. waiting for prompt), leaving no real ambiguity.

    Naming Consistency4/5

    Names mostly follow a verb_noun pattern (create_session, close_session, list_sessions, get_output), with a few bare verbs (execute, interrupt) that still clearly indicate actions. The style is consistent and readable, with only minor deviation from the noun suffix.

    Tool Count5/5

    Seven tools is well-scoped for a debugger integration. Each tool covers a necessary aspect of session and command management without redundancy, and the count is appropriate for the complexity of CDB interaction.

    Completeness5/5

    The tool set covers the full debug session lifecycle: create, close, list, execute arbitrary commands, and handle asynchronous output (poll, wait, interrupt). There are no obvious dead ends—any CDB command can be run, and pending operations can be managed. The only theoretical gap (dedicated breakpoint tools) is handled by the generic execute tool.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      An MCP server for debugging Windows processes using WinDbg and CDB. It enables users to attach to processes, manage breakpoints, inspect memory, and control execution flow through natural language.
      2
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to interact with GDB for debugging via the MCP protocol. Supports setting breakpoints, stepping through code, inspecting memory and registers, and more.
      85
      MIT