.NET Debugger for MCP

DotnetDebugger.Mcp

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.MCP until the first release, and GitHub redirects the old name. The SHARPDBG_* settings

were renamed to DOTNET_DEBUGGER_MCP_* in the release that followed 0.6.3; the old names are no

longer read.

What it can do

• Attach to a running .NET process, or launch one and stop before its first line executes
• Set breakpoints by file and line or by method name, with conditions and hit counts
• Step over, into and out of code, and read the call stack for any thread
• Inspect local variables, expand objects member by member, and evaluate C# expressions
• Break on exceptions - all of them, only the unhandled ones, or only the types you name - and read what was thrown
• Read the debuggee's stdout and stderr
• Debug more than one process at once, each with its own breakpoints and stops
• Debug a .NET MAUI app on an Android emulator or phone, an iOS simulator or device, or this Mac as a Mac Catalyst app - building it and stopping before its first line, same as a desktop program
• Search embedded documentation on ICorDebug, the Debug Adapter Protocol and expression evaluation

What it cannot do

Some of these need changes in the underlying debugger rather than here.

• Report the exit code of a process it attached to. 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.
• Debug a self-contained single-file publish. The runtime is packed inside the executable, so the debugger shim cannot find it to load the matching components. The attempt fails immediately with 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.
• Watch expressions, hot reload and data breakpoints are not implemented.

Requirements

• .NET 10 SDK or later
• An MCP-compatible client, such as Claude Code or Claude Desktop
• Windows, macOS or Linux

Install

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:

claude mcp add dotnet-debugger -- dotnet tool exec DotnetDebugger.Mcp --version 0.8.0 --yes

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.

VS Code, in .vscode/mcp.json for the workspace, or with MCP: Open User Configuration for every workspace. VS Code calls the section servers, not mcpServers:

{

"servers": { "dotnet-debugger": { "type": "stdio", "command": "dotnet", "args": ["tool", "exec", "DotnetDebugger.Mcp", "--version", "0.8.0", "--yes"] } } }

Claude Desktop, by editing ~/.config/Claude/claude_desktop_config.json on macOS and Linux, or %APPDATA%\Claude\claude_desktop_config.json on Windows:

{

"mcpServers": { "dotnet-debugger": { "command": "dotnet", "args": ["tool", "exec", "DotnetDebugger.Mcp", "--version", "0.8.0", "--yes"] } } }

dnx DotnetDebugger.Mcp --version 0.8.0 --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.

Why the version is pinned

Every command here names a version. Without --version, dotnet tool exec resolves the package on each start, so a newly published release would run on the next session without anyone having chosen it. A debugger can read and change everything in the process it attaches to, so which build of it runs should be a decision rather than a side effect. Change the version in the command to upgrade; the latest is on nuget.org.

Installing the tool once instead avoids the resolution step on every start:

dotnet tool install -g DotnetDebugger.Mcp --version 0.8.0

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.

Checking where a package came from

Releases after 0.6.1 carry a build provenance attestation: a statement, signed through GitHub, that this repository's release workflow built that package from a given commit. To check one before mirroring or installing it, download the .nupkg from nuget.org and run:

gh attestation verify DotnetDebugger.Mcp.<version>.nupkg --repo nevse/dotnet-debugger-mcp

nuget.org adds its own repository signature to every package it accepts, which changes the file, so the release workflow attests both: the package as built, attached to the GitHub Release, and nuget.org's copy, once it has checked that copy holds exactly what was built. For 0.6.2 only the first exists: verify the copy from gh release download v0.6.2 -R nevse/dotnet-debugger-mcp -p '*.nupkg'.

Upgrading

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:

dotnet tool exec DotnetDebugger.Mcp --version 0.1.1 --yes

With the version pinned, upgrading is changing it in the command, and the question does not arise. An installed tool is upgraded explicitly too:

dotnet tool update -g DotnetDebugger.Mcp --version <new version>

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.

A worked example

Catching a program before it has run a single line, which is the case attaching cannot reach:

User: "My app throws before it prints anything. Find out why."

Claude: [launch_program("/path/to/bin/Debug/net10.0/MyApp.dll")] "Prepared, not running yet. Setting a breakpoint on the first line of Main."

Claude: [set_breakpoint("/path/to/Program.cs", 12)] "Breakpoint set. It is unverified for now — nothing can bind before the program has loaded its modules — and takes effect when the program starts."

Claude: [start_program()] Claude: [wait_for_stop()] "Stopped at Program.cs:12, before a single line has run."

Claude: [step_over(thread_id: 1)] Claude: [get_variables(frame_id: 0)] "configPath is null, and the next line passes it to File.ReadAllText."

Claude: [get_program_output()] "The program printed nothing before the throw, which matches what you saw."

Tools

Each tool declares MCP annotations, so a client that reads them can approve the read-only ones without asking and still ask for the rest. The last column says which:

• read-only - reads the session or the machine and changes nothing.
• session - changes only the debug session: stepping, resuming, removing a breakpoint. Not destructive.
• runs getters - reads that run the debuggee's own code: the debugger calls ToString, property getters and DebuggerDisplay to show a value. Not marked read-only, though not destructive either.
• ends a launched program - destructive: a program the session launched is killed.
• runs code - destructive and open-world: it starts, builds or evaluates code the agent chose. A breakpoint's condition is a C# expression evaluated at every hit, so setting one counts.

The annotations are hints, and a client is free to ignore them.

Debugging

.NET MAUI

Needs a one-off setup - see Debugging a .NET MAUI app.

Breakpoints

Execution and inspection

| pause_execution | Break into the debugger where the program currently is | ses