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.

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

   • Install uv from https://docs.astral.sh/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