DebugMcpServer
MCP server for interactive debugging via the Debug Adapter Protocol (DAP). Attach to processes, set breakpoints, step through code, inspect variables β all through MCP tool calls.
Ask AI about DebugMcpServer
Powered by Claude Β· Grounded in docs
I know everything about DebugMcpServer. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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:
| Platform | Asset |
|---|---|
| Windows x64 | debug-mcp-server-win-x64.zip |
| Linux x64 | debug-mcp-server-linux-x64.tar.gz |
| macOS x64 | debug-mcp-server-osx-x64.tar.gz |
| macOS ARM64 | debug-mcp-server-osx-arm64.tar.gz |
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
Alternative: Build from source
{
"mcpServers": {
"debugger": {
"command": "dotnet",
"args": ["run", "--project", "/path/to/DebugMcpServer/src/DebugMcpServer"]
}
}
}
CLI: claude mcp add debugger -- dotnet 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"
}
}
}
}
Alternative: Build from source
{
"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"
}
}
}
Alternative: Build from source
{
"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"
}
}
}
Alternative: Build from source
{
"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"
}
}
}
Alternative: Build from source
{
"mcpServers": {
"debugger": {
"command": "dotnet",
"args": ["run", "--project", "/path/to/DebugMcpServer/src/DebugMcpServer"]
}
}
}
Note: The
debug-mcp-servercommand is available on your PATH after runningdotnet tool install -g DebugMcpServer. If you are using the build-from-source configs, replace/path/to/DebugMcpServerwith 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
| Tool | Description |
|---|---|
list_adapters | List configured debug adapters |
list_processes | Find running processes by name (local or remote via SSH) |
attach_to_process | Attach debugger to a running process by PID |
launch_process | Start a process under the debugger |
detach_session | Disconnect debugger, process continues running |
terminate_process | Kill the debugged process and end the session |
list_sessions | List all active debug sessions with state |
load_dump_file | Load a crash dump or core dump for post-mortem debugging |
Breakpoints
| Tool | Description |
|---|---|
set_breakpoint | Set breakpoint by file + line, with optional condition and hitCount |
remove_breakpoint | Remove breakpoint by file + line |
list_breakpoints | List all active breakpoints in a session |
set_function_breakpoints | Break on function entry by name |
set_exception_breakpoints | Break on thrown/unhandled exceptions |
get_exception_info | Get exception type, message, and stack trace when stopped on one |
set_data_breakpoint | Break when a variable's value changes (watchpoint) |
Execution Control
| Tool | Description |
|---|---|
continue_execution | Resume execution (configurable wait timeout, default 3s) |
step_over | Step over current line |
step_in | Step into function call |
step_out | Step out of current function |
pause_execution | Pause a running process |
get_pending_events | Drain queued DAP events (output, stopped, thread) |
Inspection
| Tool | Description |
|---|---|
get_source | View source code around current stop location |
get_callstack | Get stack frames for active thread |
get_variables | Inspect variables in a stack frame or expand nested objects |
set_variable | Modify a variable's value while paused |
evaluate_expression | Evaluate any expression in the current frame context |
list_threads | List all threads |
change_thread | Switch active thread |
get_modules | List loaded modules/assemblies |
disassemble | Disassemble machine code at a memory address |
get_loaded_sources | List all source files the adapter knows about |
Memory
| Tool | Description |
|---|---|
read_memory | Read raw bytes from a memory address (returns hex dump) |
write_memory | Write raw bytes to a memory address |
Escape Hatch
| Tool | Description |
|---|---|
send_dap_request | Send any arbitrary DAP command directly |
.NET Dump Analysis (ClrMD)
| Tool | Description |
|---|---|
load_dotnet_dump | Load a .NET dump file for analysis (uses ClrMD β no external tools required) |
dotnet_dump_threads | List all managed threads with stack traces |
dotnet_dump_exceptions | Show exceptions on all threads with inner exception chain |
dotnet_dump_stack_objects | Show objects on a thread's stack (locals, params, this pointers) |
dotnet_dump_heap_stats | Heap statistics β object counts and sizes by type (filterable) |
dotnet_dump_find_objects | Find all instances of a type on the heap with addresses |
dotnet_dump_inspect | Inspect a .NET object at a given address (fields, arrays, strings) |
dotnet_dump_gc_roots | Find GC roots keeping an object alive (memory leak diagnosis) |
dotnet_dump_memory_stats | GC heap overview: generation sizes, segments, committed memory |
dotnet_dump_async_state | Analyze async Tasks and state machines (deadlock diagnosis) |
Native Dump Analysis (DbgEng β Windows only)
| Tool | Description |
|---|---|
load_native_dump | Load a Windows .dmp file for native analysis (uses dbgeng.dll β the WinDbg engine) |
native_dump_command | Run any WinDbg command (k, ~*k, dv, r, lm, u, dd, !analyze -v, etc.) |
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.exeunder 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
_balancevariable β 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
orderItemsvariable β show me its properties"You: "What threads are running? Switch to thread 5"
You: "What modules are loaded?"
Modifying State
You: "Set the
retryCountvariable 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 > 1000on 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
totalvariable 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:
| Adapter | Config Name | Dump Formats | License |
|---|---|---|---|
| netcoredbg | dotnet | Linux/macOS .NET core dumps | MIT |
| cpptools (OpenDebugAD7) | cpp | Linux core dumps | VS Code Extension |
| lldb-dap | lldb | Core dumps, Mach-O cores | Open source |
| ClrMD (built-in) | (no config) | .NET dumps on any platform | MIT |
Platform guidance for dump debugging
| Dump Type | Platform | Approach |
|---|---|---|
| .NET dump | Any | load_dotnet_dump β ClrMD built-in, no config needed (threads, exceptions, heap, GC roots) |
| .NET core dump | Linux/macOS | load_dump_file with dotnet adapter β full DAP debugging (variables, expressions) |
| Native C/C++ core dump | Linux/macOS | load_dump_file with cpp or lldb adapter β DAP debugging |
Native C/C++ .dmp | Windows | Not supported β see note below |
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 (viaload_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
.dmpfiles are not supported. Microsoft's vsdbg/cppvsdbg adapter can open Windows.dmpfiles 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_adaptersshows"status": "found"or"not_found". - Bare command name (e.g.,
netcoredbg): The user has placed the adapter on their PATH. The server passes it toProcess.Startwhich resolves it from PATH.list_adaptersshows"status": "bare_command"since the server cannot verify PATH resolution without executing the binary.
- Full path (e.g.,
- 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_adaptersto 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" }
]
}
}
| Field | Description |
|---|---|
Adapters[].Name | Friendly name used in tool calls |
Adapters[].Path | Path to the debug adapter executable. Supports full paths (e.g., /usr/local/bin/netcoredbg) or bare command names (e.g., netcoredbg) if the adapter is on your PATH. |
Adapters[].AdapterID | DAP adapter identifier (e.g., coreclr, python, node) |
Adapters[].RemotePath | Adapter path on remote machines (used with SSH) |
Adapters[].DumpArgumentName | DAP launch argument name for dump file path (e.g., coreDumpPath, coreFile, dumpPath). Required for load_dump_file support. |
AttachTimeoutSeconds | Max time to wait for adapter during attach/launch |
MaxPendingEvents | Event channel buffer size per session |
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?
| Dump type | Platform | Tool | Config needed? |
|---|---|---|---|
| .NET dump | Any | load_dotnet_dump | No β ClrMD is built-in |
Windows .dmp (native C/C++) | Windows | load_native_dump | No β DbgEng is built into Windows |
| Linux/macOS .NET core dump | Linux/macOS | load_dump_file with dotnet | Yes β netcoredbg path |
| Linux core dump (C/C++) | Linux | load_dump_file with cpp | Yes β OpenDebugAD7 path |
| macOS Mach-O core | macOS | load_dump_file with lldb | Yes β lldb-dap path |
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?
| Adapter | Typical location |
|---|---|
| OpenDebugAD7 (cpp) | ~/.vscode/extensions/ms-vscode.cpptools-*/debugAdapters/bin/OpenDebugAD7 |
| netcoredbg (dotnet) | Download from github.com/Samsung/netcoredbg |
| debugpy (python) | pip install debugpy, adapter at python -m debugpy.adapter |
| lldb-dap (lldb) | apt install lldb or brew install llvm |
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
