Debug MCP Server

A Model Context Protocol (MCP) server that provides interactive debugging capabilities for AI assistants using the Debug Adapter Protocol (DAP).

Attach to running processes, set breakpoints, step through code, inspect variables, evaluate expressions — all through MCP tool calls. Supports multiple debug adapters (.NET, Python, Node.js, C++), parallel debug sessions, and remote debugging over SSH.

Features

• Multi-adapter support — Configure multiple debug adapters (netcoredbg, debugpy, js-debug, cpptools) and select which one to use per session
• Full debugging workflow — Attach/launch, breakpoints (line, conditional, function, exception, data), stepping, variable inspection, expression evaluation
• Dump file debugging — Load crash dumps and core dumps for post-mortem analysis with stack traces, variable inspection, memory reads, and disassembly
• Parallel sessions — Debug multiple processes simultaneously with concurrent request processing
• Remote debugging — Debug processes on remote machines via SSH with zero additional setup
• Memory access — Read and write raw memory at arbitrary addresses
• Source view — View source code around the current stop location with line numbers
• Human-readable errors — Common DAP error codes are translated into actionable guidance

Installation

dotnet tool (recommended)

Requires .NET 8 SDK or later.

dotnet tool install -g DebugMcpServer

This installs the debug-mcp-server command globally on your PATH.

Self-contained binaries

Pre-built binaries with no .NET SDK required are available on GitHub Releases:

Build from source

git clone https://github.com/ms-bassem-srouji/DebugMcpServer.git
cd DebugMcpServer
dotnet build

Quick Start

Prerequisites

• A DAP-compatible debug adapter:
  • .NET: netcoredbg (recommended)
  • Python: debugpy
  • Node.js: js-debug
  • C++: cpptools

Configure

Create a config file at ~/.config/debug-mcp-server/appsettings.json with your adapter paths:

{
  "Debug": {
    "Adapters": [
      { "Name": "dotnet", "Path": "C:\\tools\\netcoredbg\\netcoredbg.exe", "AdapterID": "coreclr", "RemotePath": "/usr/local/bin/netcoredbg" },
      { "Name": "python", "Path": "/usr/bin/debugpy", "AdapterID": "python" }
    ]
  }
}

This user-level config overrides the bundled defaults and is preserved across tool updates. If you built from source, you can also edit src/DebugMcpServer/appsettings.json directly.

MCP Client Configuration

Install for Your AI Client

Claude Code (CLI & VS Code Extension)

Add to your project's .mcp.json file (or ~/.claude/settings.json for global):

{
  "mcpServers": {
    "debugger": {
      "command": "debug-mcp-server"
    }
  }
}

Or via the CLI:

claude mcp add debugger -- debug-mcp-server

{
  "mcpServers": {
    "debugger": {
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/DebugMcpServer/src/DebugMcpServer"]
    }
  }
}

VS Code (GitHub Copilot)

Add to your workspace .vscode/mcp.json:

{
  "servers": {
    "debugger": {
      "type": "stdio",
      "command": "debug-mcp-server"
    }
  }
}

Or add to your user settings (settings.json):

{
  "mcp": {
    "servers": {
      "debugger": {
        "type": "stdio",
        "command": "debug-mcp-server"
      }
    }
  }
}

{
  "servers": {
    "debugger": {
      "type": "stdio",
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/DebugMcpServer/src/DebugMcpServer"]
    }
  }
}

GitHub Copilot CLI

Add to ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "debugger": {
      "type": "stdio",
      "command": "debug-mcp-server"
    }
  }
}

{
  "mcpServers": {
    "debugger": {
      "type": "stdio",
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/DebugMcpServer/src/DebugMcpServer"]
    }
  }
}

Cursor

Add to your project's .cursor/mcp.json:

{
  "mcpServers": {
    "debugger": {
      "command": "debug-mcp-server"
    }
  }
}

{
  "mcpServers": {
    "debugger": {
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/DebugMcpServer/src/DebugMcpServer"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "debugger": {
      "command": "debug-mcp-server"
    }
  }
}

{
  "mcpServers": {
    "debugger": {
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/DebugMcpServer/src/DebugMcpServer"]
    }
  }
}

Note: The debug-mcp-server command is available on your PATH after running dotnet tool install -g DebugMcpServer. If you are using the build-from-source configs, replace /path/to/DebugMcpServer with the actual path where you cloned the repository. On Windows, use backslashes or forward slashes (e.g., C:/repos/DebugMcpServer/src/DebugMcpServer).

Tools

Session Management

Breakpoints

Execution Control

Inspection

Memory

Escape Hatch

.NET Dump Analysis (ClrMD)

Native Dump Analysis (DbgEng — Windows only)

Sample Prompts

These are natural language prompts you can give to your AI assistant. The assistant will translate them into the appropriate MCP tool calls automatically.

Getting Started

You: "What debug adapters do you have?"

You: "Find the MyWebApp process"

You: "Attach the debugger to process 1234 using the dotnet adapter"

You: "Launch bin/Debug/net8.0/MyApp.exe under the debugger"

Setting Breakpoints

You: "Set a breakpoint at line 42 in Program.cs"

You: "Add a conditional breakpoint on line 85 of OrderService.cs when orderId equals 100"

You: "Break when we enter the ProcessPayment function"

You: "Break on any unhandled exceptions"

You: "Set a watchpoint on the _balance variable — break when it changes"

You: "Show me all active breakpoints"

Execution Control

You: "Resume execution"

You: "Resume and wait 20 seconds for the next breakpoint"

You: "Step over the current line"

You: "Step into this function call"

You: "Step out of the current function"

You: "Pause the process"

Inspecting State

You: "Show me the source code around where we stopped"

You: "What's the call stack?"

You: "Show me the local variables"

You: "What is the value of customer.Name?"

You: "Evaluate orders.Where(o => o.Status == "Pending").Count()"

You: "Expand the orderItems variable — show me its properties"

You: "What threads are running? Switch to thread 5"

You: "What modules are loaded?"

Modifying State

You: "Set the retryCount variable to 0"

You: "Write 0xFF to memory address 0x7FFE4A3B1000"

Breakpoint Management

You: "Remove the breakpoint at line 42 in Program.cs"

You: "Clear all breakpoints and resume"

Exception Handling

You: "Break on all exceptions"

You: "What exception just occurred? Show me the details and stack trace"

You: "Break only on unhandled exceptions"

Session Management

You: "Is the process still running or paused?"

You: "List all debug sessions"

You: "Stop debugging and detach"

You: "Kill the process and end the debug session"

Remote Debugging

You: "List processes on the remote server user@192.168.1.50"

You: "Attach to process 5678 on user@production-server using the dotnet adapter"

You: "Debug the MyApp process on the staging server via SSH"

Dump File Debugging

You: "Load the crash dump at /tmp/core.12345 using the cpp adapter"

You: "Show me the call stack from this dump file"

You: "What threads were running when this crash happened?"

You: "Disassemble 20 instructions at the crash address"

You: "What are the local variables at the crash site?"

You: "Show me the loaded source files in this dump"

.NET Dump Analysis

You: "Open the .NET crash dump at crash_12345.dmp"

You: "Show me the managed stack traces for all threads"

You: "What exception caused the crash?"

You: "What objects were on the crashing thread's stack?"

You: "Show me heap statistics — what types are using the most memory?"

You: "Find all instances of MyApp.Order on the heap and show me their fields"

You: "What's keeping this object alive? Show me the GC roots"

You: "How much memory is the GC heap using? Show me generation sizes"

You: "Are there any stuck async tasks? Show me the async state"

You: "I think we have an async deadlock — show me all tasks that are WaitingForActivation"

Advanced Workflows

You: "Attach to the MyApp process, set a breakpoint when orderTotal > 1000 on line 55 of CheckoutService.cs, then resume and wait for it to hit"

You: "I'm debugging a race condition — attach to the process, break on all exceptions, and when it stops show me the call stack and all local variables"

You: "Step through the next 5 lines and show me how the total variable changes at each step"

You: "Debug two processes side by side — attach to both PIDs 1234 and 5678, set the same breakpoint in both, and resume both"

Usage Examples (Tool Calls)

For reference, here's how the prompts above map to actual tool calls:

Basic Debugging

1. list_processes(filter: "MyApp")           → find PID
2. attach_to_process(pid: 1234)              → get sessionId, process paused
3. set_breakpoint(file: "Program.cs", line: 42, condition: "x > 10")
4. continue_execution()                      → hits breakpoint
5. get_source()                              → see code context
6. get_callstack()                           → get frame IDs
7. get_variables(frameId: 1)                 → inspect locals
8. evaluate_expression(expression: "myList.Count")
9. step_over()                               → next line
10. detach_session()                          → done

Remote Debugging over SSH

1. list_processes(host: "user@server", filter: "myapp")
2. attach_to_process(pid: 5678, host: "user@server", adapter: "dotnet")
3. ... all tools work the same — DAP flows through SSH

Dump File Debugging

1. load_dump_file(dumpPath: "/tmp/core.12345", program: "/app/myapp", adapter: "cpp")
   → sessionId, process paused at crash site
2. get_callstack()                           → see crash stack trace
3. list_threads()                            → see all threads at crash time
4. get_variables(frameId: 0)                 → inspect locals at crash frame
5. disassemble(memoryReference: "0x4015a0")  → see assembly at crash address
6. get_loaded_sources()                      → discover available source files
7. read_memory(memoryReference: "0x7ffd1000") → examine raw memory
8. evaluate_expression(expression: "strlen(buffer)")
9. detach_session()                          → done

Supported adapters and dump formats:

Platform guidance for dump debugging

Why two approaches? DAP debugging (via load_dump_file) gives structured variable inspection, source mapping, and expression evaluation — but needs a compatible debug adapter. ClrMD (via load_dotnet_dump) provides .NET-specific deep analysis (heap stats, GC roots, exception chains) directly as a built-in library — no external tools or configuration needed.

Windows native .dmp files are not supported. Microsoft's vsdbg/cppvsdbg adapter can open Windows .dmp files but has a restrictive license (Visual Studio/VS Code use only) and uses a non-standard DAP protocol flow that is not compatible with this MCP server. For Windows native dump analysis, use WinDbg or Visual Studio directly. For .NET dumps on Windows, load_dotnet_dump (ClrMD) works fully.

Execution control tools (continue, step_*, pause) are automatically blocked on dump sessions with a clear error message.

.NET Dump Analysis (ClrMD)

For .NET dumps, use the built-in ClrMD integration (MIT-licensed, no external tools required):

1. load_dotnet_dump(dumpPath: "crash_12345.dmp")
   → sessionId + runtime info (threads, exceptions, app domains)
2. dotnet_dump_threads()                          → all managed threads with stack traces
3. dotnet_dump_exceptions()                       → exceptions with type, message, inner chain
4. dotnet_dump_stack_objects(osThreadId: "0x9F64") → objects on the crashing thread's stack
5. dotnet_dump_heap_stats(filter: "Order")         → find specific types on the heap
6. dotnet_dump_find_objects(typeName: "Order")     → get addresses of all Order instances
7. dotnet_dump_inspect(address: "0x7fff..")        → object fields, array elements, string values
8. dotnet_dump_gc_roots(address: "0x7fff..")       → what's keeping this object alive?
9. dotnet_dump_memory_stats()                      → GC generation sizes, committed memory
10. dotnet_dump_async_state()                      → async Tasks status, stuck awaits
11. detach_session()                               → close session

Powered by Microsoft.Diagnostics.Runtime (ClrMD) — the same library that dotnet-dump and Visual Studio use internally. No external tools to install.

Requires SSH key-based authentication (password auth is not supported since the MCP server runs non-interactively).

Parallel Sessions

1. attach_to_process(pid: 1234)  → sessionId: "aaa"
2. attach_to_process(pid: 5678)  → sessionId: "bbb"
3. continue_execution(sessionId: "aaa")           → runs in parallel
4. get_callstack(sessionId: "bbb")                → works immediately
5. list_sessions()                                 → see both sessions

Architecture

MCP Client (Claude, etc.)
    │
    │ JSON-RPC over stdio
    │
┌───▼───────────────────────────┐
│  McpHostedService             │  ← Concurrent request dispatch
│  (MCP protocol handler)       │     with stdout write lock
├───────────────────────────────┤
│  Tools (31 total)             │  ← Each tool = one MCP capability
│  AttachToProcessTool          │
│  SetBreakpointTool            │
│  GetVariablesTool  ...        │
├───────────────────────────────┤
│  DapSessionRegistry           │  ← Thread-safe session store
│  (ConcurrentDictionary)       │     (multiple parallel sessions)
├───────────────────────────────┤
│  DapSession                   │  ← DAP protocol over stdin/stdout
│  (per debug adapter process)  │     or piped through SSH
├───────────────────────────────┤
│  Debug Adapter (netcoredbg)   │  ← Local process or remote via SSH
│  Debug Adapter (debugpy)      │
└───────────────────────────────┘

Security

The MCP server only executes debug adapter processes that are explicitly configured in appsettings.json by the user. It does not auto-discover, download, or execute binaries from arbitrary locations.

• No auto-discovery: The server will not scan your system to find debug adapters. Every adapter must be explicitly configured by the user.
• Two path modes supported:
  • Full path (e.g., /usr/local/bin/netcoredbg): The server verifies the file exists. list_adapters shows "status": "found" or "not_found".
  • Bare command name (e.g., netcoredbg): The user has placed the adapter on their PATH. The server passes it to Process.Start which resolves it from PATH. list_adapters shows "status": "bare_command" since the server cannot verify PATH resolution without executing the binary.
• No remote code execution: Debug adapters run as local child processes with the same permissions as the MCP server. SSH remote debugging connects to a user-specified host only.
• Adapter diagnostics: Use list_adapters to see the status of every configured adapter, install hints for missing ones, and the config file location.
• User config overrides: User-level config (~/.config/debug-mcp-server/appsettings.json) takes precedence over bundled defaults.

Configuration

appsettings.json

The default config ships with bare command names — if the adapter is on your PATH, it works out of the box. Override with full paths in your user config for explicit control.

{
  "Debug": {
    "Adapters": [
      {
        "Name": "dotnet",
        "Path": "netcoredbg",
        "AdapterID": "coreclr",
        "RemotePath": "/usr/local/bin/netcoredbg",
        "DumpArgumentName": "coreDumpPath"
      },
      {
        "Name": "cpp",
        "Path": "OpenDebugAD7",
        "AdapterID": "cppdbg",
        "DumpArgumentName": "coreDumpPath"
      }
    ],
    "AttachTimeoutSeconds": 30,
    "StepTimeoutSeconds": 3,
    "ContinueTimeoutSeconds": 25,
    "MaxPendingEvents": 100
  }
}

User-level overrides (~/.config/debug-mcp-server/appsettings.json) can use full paths:

{
  "Debug": {
    "Adapters": [
      { "Name": "dotnet", "Path": "/usr/local/bin/netcoredbg", "AdapterID": "coreclr", "DumpArgumentName": "coreDumpPath" },
      { "Name": "cppvsdbg", "Path": "C:\\Program Files\\VS\\vsdbg.exe", "AdapterID": "cppvsdbg", "DumpArgumentName": "dumpPath" }
    ]
  }
}

Testing

dotnet test

The test suite includes 257+ deterministic unit tests with no external dependencies (no sleeps, no reflection, no network calls).

Project Structure

DebugMcpServer/
├── src/DebugMcpServer/
│   ├── Dap/                  # DAP protocol: session, events, SSH helper, error mapping
│   ├── Options/              # Configuration models (adapters, timeouts)
│   ├── Server/               # MCP hosted service (stdio transport, concurrent dispatch)
│   └── Tools/                # All 29 MCP tools
├── tests/DebugMcpServer.Tests/
│   ├── Fakes/                # FakeSession, FakeSessionRegistry
│   └── Tests/                # Unit tests for every tool
└── samples/
    ├── SampleTarget/          # Sample .NET app for live debugging
    ├── CrashTarget/           # .NET app that generates a self-dump for testing
    └── NativeCrashTarget/     # C++ app that generates a native dump (CMake)

FAQ

Which adapter do I use for dump files?

Zero-config on Windows: Both .NET and native Windows dumps work out of the box — no adapters to install or configure. ClrMD and DbgEng are built-in.

Where do I find the adapter executables?

How do I configure an adapter?

Add adapter paths to ~/.config/debug-mcp-server/appsettings.json (user config, not tracked by git):

{
  "Debug": {
    "Adapters": [
      { "Name": "dotnet", "Path": "/usr/local/bin/netcoredbg", "AdapterID": "coreclr", "DumpArgumentName": "coreDumpPath" },
      { "Name": "cpp", "Path": "/path/to/OpenDebugAD7", "AdapterID": "cppdbg", "DumpArgumentName": "coreDumpPath" }
    ]
  }
}

Use list_adapters to verify your configuration — it shows which adapters are found, missing, or configured as bare command names.

Do I need external tools for .NET dump analysis?

No. The MCP server includes ClrMD (Microsoft.Diagnostics.Runtime) — the same library that Visual Studio and dotnet-dump use internally. Just call load_dotnet_dump with a .dmp file and use the structured tools (dotnet_dump_threads, dotnet_dump_exceptions, dotnet_dump_heap_stats, etc.). No external tools to install.

License

MIT