The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the .NET Debugger for MCP listing page.
An MCP server that lets an AI assistant debug .NET programs: launch or attach to a process, set breakpoints, step through code, inspect variables and evaluate expressions. It also carries a searchable reference on how .NET debuggers work internally.
Published on NuGet as DotnetDebugger.Mcp.
Built on clrdbg, driven over the Debug Adapter Protocol. The
debugger travels inside the package and runs as a child process, so a crash in native debugging code
costs the debug session rather than the server.
Origin. A fork of decriptor/SharpDbg.MCP, now far enough from it to carry its own name: the debugger layer speaks the Debug Adapter Protocol instead of calling a debugger's internal API, the debugger underneath has since changed from SharpDbg to clrdbg, launching a program under the debugger is new, and the two have not shared a commit since. This repository was called
SharpDbg.MCPuntil the first release; GitHub redirects the old name, and the project files andSHARPDBG_*settings still carry it.
Some of these need changes in the underlying debugger rather than here.
exit_code is null there. The debugger
reads the code off a process it started itself and has none for one it was pointed at, so for an
attached process there is nothing to report — and the protocol cannot say "unknown", only 0,
which would be a number this server made up. A program started with launch_program does report
its real code.CORDBG_E_DEBUG_COMPONENT_MISSING (0x80131C3C), reported as
Attempting to register for runtime startup failed: -2146231236. Self-contained on its own works,
and single-file on its own works; only the combination does not.One package carries the debugger and its native shims for every platform, so the same configuration works everywhere. There is nothing to clone or build.
Claude Code, for the current project:
Add --scope user to make it available in every project, or --scope project to write a .mcp.json
that is committed and shared with your team.
Claude Desktop, by editing ~/.config/Claude/claude_desktop_config.json on macOS and Linux, or
%APPDATA%\Claude\claude_desktop_config.json on Windows:
dnx DotnetDebugger.Mcp --yes is the shorter equivalent, and the form NuGet.org suggests. Prefer
dotnet tool exec in a client launched from a desktop environment rather than from a shell: dnx
lives in the SDK directory, which such a client often does not have on its PATH, while dotnet
reliably is.
A client only connects its MCP servers when a session starts, so restart it after changing the
configuration. To confirm the server is there, run claude mcp list or ask the client to list .NET
processes.
Installing the tool once avoids the resolution step on every start and keeps the version fixed until you change it:
The command is then dotnet-debugger-mcp, with no arguments. This needs ~/.dotnet/tools on your
PATH, which is why it is not the default suggestion: a client that cannot find the command fails
the same way a wrong path does.
dotnet tool exec can keep running a version it has already downloaded, even after a newer one is
published and indexed. Nothing looks wrong when it does: the server starts, the client reports it as
connected, and the only sign is that the new release's tools are missing.
Measured while releasing 0.1.1. With only 0.1.0 in the local package folder, the unpinned command kept running 0.1.0, and clearing the NuGet HTTP cache did not change that. Naming the version once fetched the new package, after which the unpinned command used it too:
Installing the tool avoids the question entirely, because then upgrading is explicit:
To see which version is actually running, ask the client to list this server's tools, or read the first line the server writes to stderr — it names the version at startup. A client's own health check reports only that the process started, not what it is.
Catching a program before it has run a single line, which is the case attaching cannot reach:
| Tool | What it does |
|---|---|
list_dotnet_processes | List the .NET processes running on this machine |
attach_to_process | Attach the debugger to a running .NET process |
launch_program | Prepare a program to run under the debugger, stopped before it starts |
start_program | Run the program prepared by launch_program |
get_process_status | Report whether the session is running, stopped, and where |
wait_for_stop | Block until the debuggee stops, instead of polling |
get_program_output | Read what the debuggee wrote to stdout and stderr |
detach_from_process | Detach, leaving the process running |
list_sessions | List open sessions and what each is debugging |
close_session | Close a session, detaching first if needed |
| Tool | What it does |
|---|---|
set_breakpoint | Set or update a breakpoint at a file and line, with an optional condition or hit count |
set_function_breakpoint | Set a breakpoint on a method by name, when the file and line are not known |
remove_breakpoint | Remove a breakpoint of either kind |
list_breakpoints | List this session's breakpoints and whether each is verified |
set_exception_break_mode | Choose which exceptions stop the program: all, unhandled, or named types |
| Tool | What it does |
|---|---|
continue_execution | Resume until the next breakpoint or exit |
pause_execution | Break into the debugger where the program currently is |
step_over, step_into, step_out | Step by line, into a call, or out of the current method |
get_threads | List the threads in the debuggee |
get_stack_trace | Read the call stack for a thread |
get_variables | Read the locals of a stack frame |
expand_variable | Expand an object into its members, which may expand further |
evaluate_expression | Evaluate a C# expression in the context of a frame |
get_exception_info | Read the type, message, HResult, source and stack trace of what was thrown |
| Tool | What it does |
|---|---|
search_debugging_concepts | Search the embedded documentation |
explain_icordebug_interface | Explain a specific ICorDebug interface |
get_debugging_flow | Walk through a debugging operation step by step |
list_debugging_concepts | Browse the concept catalogue by category |
A breakpoint binds through the target's symbols, so the debuggee must be built with portable PDBs
sitting next to its assembly. A missing or mismatched PDB is the most common reason set_breakpoint
answers verified: false with No symbols have been loaded for this document.
Debug builds already do this. For a Release build, or any project that changes the defaults:
Optimized code also moves locals out of reach, so get_variables is only fully useful with
<Optimize>false</Optimize>.
macOS will not let a debugger take another process's task port unless the target carries
com.apple.security.get-task-allow. A program run through the dotnet muxer is fine, because the
muxer ships with that entitlement; an apphost produced by dotnet publish is ad-hoc signed with no
entitlements at all.
The debugger's own side of this needs nothing from you: the debug adapter is started through the
dotnet muxer as well, so it inherits the entitlements that let it debug at all.
On a desktop session this does not affect you. Debugging a self-contained publish carrying no entitlements is verified to work there.
It matters in a headless environment, such as a CI runner, and it fails badly when it does: macOS refuses by blocking rather than returning an error, so the debugger stops responding and the call never comes back. If a launch or attach hangs on macOS with no error at all, sign the target and try again:
with get-task-allow.entitlements containing:
SHARPDBG_JUST_MY_CODE=false does not make a step stop in code you have no symbols for. Neither
setting does: a step that lands in a module without symbols steps straight back out, because there is
no source to report a location against. A step through an interpolated string goes through
System.Private.CoreLib and comes back to the next statement of your own method either way.
What the setting changes is which modules get their symbols looked for at all. With Just My Code on, only assemblies built by you are searched; with it off, every module is, so a step does surface inside a dependency you happen to have symbols for. That is what to turn it off for.
A debugger can read and change everything in the process it attaches to, so by default this server
attaches only to processes belonging to the user it runs as. attach_to_process refuses anything
else before it looks at the process at all, and list_dotnet_processes marks each entry with an
owner of current_user, other_user or unknown.
unknown is refused as well. On Windows that is what a system or elevated process looks like, since
its token cannot be opened, and treating it as your own would make the check decorative wherever the
lookup does not work.
SHARPDBG_ALLOW_OTHER_USER_PROCESSES=true lifts the restriction. The operating system still has its
own say: on Linux and macOS a normal user cannot attach to another user's process even with this
enabled, so in practice it matters when the server runs elevated or as root.
By default the server debugs one process at a time, and SHARPDBG_MAX_SESSIONS raises that. Each
session has its own process, breakpoints and stops.
attach_to_process and launch_program return a session_id. While only one session is open you
can ignore it, because every tool defaults to the only session. Taking on a second process opens a
second session rather than failing, and from then on session_id becomes required: with two
processes open, guessing which one a continue_execution was meant for would be worse than asking.
detach_from_process leaves the session open and free, so the next attach or launch reuses it rather
than taking another slot.
The default of one is deliberate. Every attach carries a risk of a native crash inside the debugging shim, so more sessions means more exposure. What such a crash costs is bounded: each session drives its own debug adapter in a process of its own, so the one that crashes takes its session with it and leaves the server and any other session running.
Every tool reports a failure the same way:
error is whatever the debugger said, kept verbatim. explanation says what the failure means and
what to do about it, for the CORDBG_E_* results the debugger raises: a process that has exited, an
operation that needs the debuggee stopped, a variable that is not live at this instruction, a frame id
from an earlier stop, another debugger already attached. It is null for failures that are not the
debugger's, such as invalid arguments.
Set these as environment variables in your client's configuration:
| Variable | Description | Default |
|---|---|---|
SHARPDBG_LOG_LEVEL | Trace, Debug, Information, Warning, Error or Critical | Information |
SHARPDBG_MAX_SESSIONS | Sessions open at once, each debugging its own process | 1 |
SHARPDBG_OPERATION_TIMEOUT_SECONDS | Bounds attaching, starting, pausing and closing a session. Steps and reads are not bounded | 30 |
SHARPDBG_EVAL_TIMEOUT_MS | Bounds anything that runs code in the debuggee: evaluate_expression and get_exception_info. Minimum 100 | 5000 |
SHARPDBG_BREAKPOINT_BIND_TIMEOUT_MS | How long to wait for a breakpoint to bind before reporting it unverified, minimum 100 | 2000 |
SHARPDBG_JUST_MY_CODE | Restrict debugging to your own code. See above before turning this off | true |
SHARPDBG_ALLOW_OTHER_USER_PROCESSES | Allow attaching to processes not owned by the current user | false |
SHARPDBG_ENABLE_DIAGNOSTICS | Detailed diagnostic logging | false |
The server does not appear in the client. Check that the path in the configuration is absolute
and correct, then fully quit and restart the client. Claude Desktop logs to ~/Library/Logs/Claude/
on macOS and %APPDATA%\Claude\logs\ on Windows.
Attaching fails. The usual causes are that the process is owned by another user (see above), has
already exited, is not a .NET process, or already has a debugger attached. list_dotnet_processes
shows what the server can see and who owns it.
A breakpoint is not hit. Check that it came back verified: true. If not, the PDB is the first
thing to look at. If it is verified and still not hit, confirm the line is actually reached and that
the file path matches the one the PDB records.
list_dotnet_processes comes back empty on macOS or Linux. Module enumeration needs permissions
there, and the server falls back to detection by process name, which misses programs whose apphost is
renamed.
A launch or attach hangs on macOS with no error. See the entitlement section above.
To see what the server is doing, set SHARPDBG_LOG_LEVEL=Trace and
SHARPDBG_ENABLE_DIAGNOSTICS=true, or run it directly and watch stderr:
The debugger is a submodule at external/clrdbg, and the build compiles it and puts the adapter next
to the server, so there is no separate step. A clone made without submodules fails the build with a
message saying so; git submodule update --init --recursive is the fix. To build against a different
clrdbg checkout - a fork carrying a fix, say - point ClrdbgSourcePath at it:
The integration tests drive a real debuggee with real breakpoints, so they are slower than the rest
and are separated by TestCategory=Integration.
To point a client at your working copy instead of the published package:
CONTRIBUTING.md covers the layout and conventions. docs/RELEASING.md covers cutting a release, including the nuget.org trusted-publishing policy that the workflow depends on but does not show.