{
  "markdown": "# DotnetDebugger.Mcp\n\nAn MCP server that lets an AI assistant debug .NET programs: launch or attach to a process, set\nbreakpoints, step through code, inspect variables and evaluate expressions. It also carries a\nsearchable reference on how .NET debuggers work internally.\n\nPublished on NuGet as [`DotnetDebugger.Mcp`](https://www.nuget.org/packages/DotnetDebugger.Mcp).\nBuilt on [clrdbg](https://github.com/JaneySprings/clrdbg), driven over the Debug Adapter Protocol. The\ndebugger travels inside the package and runs as a child process, so a crash in native debugging code\ncosts the debug session rather than the server.\n\n> **Origin.** A fork of [decriptor/SharpDbg.MCP](https://github.com/decriptor/SharpDbg.MCP), now far\n> enough from it to carry its own name: the debugger layer speaks the Debug Adapter Protocol instead of\n> calling a debugger's internal API, the debugger underneath has since changed from\n> [SharpDbg](https://github.com/MattParkerDev/sharpdbg) to clrdbg, launching a program under the\n> debugger is new, and the two have not shared a commit since. This repository was called\n> `SharpDbg.MCP` until the first release; GitHub redirects the old name, and the project files and\n> `SHARPDBG_*` settings still carry it.\n\n## What it can do\n\n- Attach to a running .NET process, or launch one and stop before its first line executes\n- Set breakpoints by file and line or by method name, with conditions and hit counts\n- Step over, into and out of code, and read the call stack for any thread\n- Inspect local variables, expand objects member by member, and evaluate C# expressions\n- Break on exceptions - all of them, only the unhandled ones, or only the types you name - and read\n  what was thrown\n- Read the debuggee's stdout and stderr\n- Debug more than one process at once, each with its own breakpoints and stops\n- Search embedded documentation on ICorDebug, the Debug Adapter Protocol and expression evaluation\n\n## What it cannot do\n\nSome of these need changes in the underlying debugger rather than here.\n\n- **Report the exit code of a process it attached to.** `exit_code` is `null` there. The debugger\n  reads the code off a process it started itself and has none for one it was pointed at, so for an\n  attached process there is nothing to report — and the protocol cannot say \"unknown\", only `0`,\n  which would be a number this server made up. A program started with `launch_program` does report\n  its real code.\n- **Debug a self-contained single-file publish.** The runtime is packed inside the executable, so the\n  debugger shim cannot find it to load the matching components. The attempt fails immediately with\n  `CORDBG_E_DEBUG_COMPONENT_MISSING` (`0x80131C3C`), reported as\n  `Attempting to register for runtime startup failed: -2146231236`. Self-contained on its own works,\n  and single-file on its own works; only the combination does not.\n- **Watch expressions**, **hot reload** and **data breakpoints** are not implemented.\n\n## Requirements\n\n- .NET 10 SDK or later\n- An MCP-compatible client, such as Claude Code or Claude Desktop\n- Windows, macOS or Linux\n\n## Install\n\nOne package carries the debugger and its native shims for every platform, so the same configuration\nworks everywhere. There is nothing to clone or build.\n\n**Claude Code**, for the current project:\n\n```bash\nclaude mcp add dotnet-debugger -- dotnet tool exec DotnetDebugger.Mcp --yes\n```\n\nAdd `--scope user` to make it available in every project, or `--scope project` to write a `.mcp.json`\nthat is committed and shared with your team.\n\n**Claude Desktop**, by editing `~/.config/Claude/claude_desktop_config.json` on macOS and Linux, or\n`%APPDATA%\\Claude\\claude_desktop_config.json` on Windows:\n\n```json\n{\n  \"mcpServers\": {\n    \"dotnet-debugger\": {\n      \"command\": \"dotnet\",\n      \"args\": [\"tool\", \"exec\", \"DotnetDebugger.Mcp\", \"--yes\"]\n    }\n  }\n}\n```\n\n`dnx DotnetDebugger.Mcp --yes` is the shorter equivalent, and the form NuGet.org suggests. Prefer\n`dotnet tool exec` in a client launched from a desktop environment rather than from a shell: `dnx`\nlives in the SDK directory, which such a client often does not have on its `PATH`, while `dotnet`\nreliably is.\n\nA client only connects its MCP servers when a session starts, so restart it after changing the\nconfiguration. To confirm the server is there, run `claude mcp list` or ask the client to list .NET\nprocesses.\n\n### Pinning a version\n\nInstalling the tool once avoids the resolution step on every start and keeps the version fixed until\nyou change it:\n\n```bash\ndotnet tool install -g DotnetDebugger.Mcp\n```\n\nThe command is then `dotnet-debugger-mcp`, with no arguments. This needs `~/.dotnet/tools` on your\n`PATH`, which is why it is not the default suggestion: a client that cannot find the command fails\nthe same way a wrong path does.\n\n### Upgrading\n\n`dotnet tool exec` can keep running a version it has already downloaded, even after a newer one is\npublished and indexed. Nothing looks wrong when it does: the server starts, the client reports it as\nconnected, and the only sign is that the new release's tools are missing.\n\nMeasured while releasing 0.1.1. With only 0.1.0 in the local package folder, the unpinned command kept\nrunning 0.1.0, and clearing the NuGet HTTP cache did not change that. Naming the version once fetched\nthe new package, after which the unpinned command used it too:\n\n```bash\ndotnet tool exec DotnetDebugger.Mcp --version 0.1.1 --yes\n```\n\nInstalling the tool avoids the question entirely, because then upgrading is explicit:\n\n```bash\ndotnet tool update -g DotnetDebugger.Mcp\n```\n\nTo see which version is actually running, ask the client to list this server's tools, or read the\nfirst line the server writes to stderr — it names the version at startup. A client's own health check\nreports only that the process started, not what it is.\n\n## A worked example\n\nCatching a program before it has run a single line, which is the case attaching cannot reach:\n\n```\nUser: \"My app throws before it prints anything. Find out why.\"\n\nClaude: [launch_program(\"/path/to/bin/Debug/net10.0/MyApp.dll\")]\n\"Prepared, not running yet. Setting a breakpoint on the first line of Main.\"\n\nClaude: [set_breakpoint(\"/path/to/Program.cs\", 12)]\n\"Breakpoint set. It is unverified for now — nothing can bind before the program has\nloaded its modules — and takes effect when the program starts.\"\n\nClaude: [start_program()]\nClaude: [wait_for_stop()]\n\"Stopped at Program.cs:12, before a single line has run.\"\n\nClaude: [step_over(thread_id: 1)]\nClaude: [get_variables(frame_id: 0)]\n\"configPath is null, and the next line passes it to File.ReadAllText.\"\n\nClaude: [get_program_output()]\n\"The program printed nothing before the throw, which matches what you saw.\"\n```\n\n## Tools\n\n### Debugging\n\n| Tool | What it does |\n|---|---|\n| `list_dotnet_processes` | List the .NET processes running on this machine |\n| `attach_to_process` | Attach the debugger to a running .NET process |\n| `launch_program` | Prepare a program to run under the debugger, stopped before it starts |\n| `start_program` | Run the program prepared by `launch_program` |\n| `get_process_status` | Report whether the session is running, stopped, and where |\n| `wait_for_stop` | Block until the debuggee stops, instead of polling |\n| `get_program_output` | Read what the debuggee wrote to stdout and stderr |\n| `detach_from_process` | Detach, leaving the process running |\n| `list_sessions` | List open sessions and what each is debugging |\n| `close_session` | Close a session, detaching first if needed |\n\n### Breakpoints\n\n| Tool | What it does |\n|---|---|\n| `set_breakpoint` | Set or update a breakpoint at a file and line, with an optional condition or hit count |\n| `set_function_breakpoint` | Set a breakpoint on a method by name, when the file and line are not known |\n| `remove_breakpoint` | Remove a breakpoint of either kind |\n| `list_breakpoints` | List this session's breakpoints and whether each is verified |\n| `set_exception_break_mode` | Choose which exceptions stop the program: all, unhandled, or named types |\n\n### Execution and inspection\n\n| Tool | What it does |\n|---|---|\n| `continue_execution` | Resume until the next breakpoint or exit |\n| `pause_execution` | Break into the debugger where the program currently is |\n| `step_over`, `step_into`, `step_out` | Step by line, into a call, or out of the current method |\n| `get_threads` | List the threads in the debuggee |\n| `get_stack_trace` | Read the call stack for a thread |\n| `get_variables` | Read the locals of a stack frame |\n| `expand_variable` | Expand an object into its members, which may expand further |\n| `evaluate_expression` | Evaluate a C# expression in the context of a frame |\n| `get_exception_info` | Read the type, message, HResult, source and stack trace of what was thrown |\n\n### Documentation\n\n| Tool | What it does |\n|---|---|\n| `search_debugging_concepts` | Search the embedded documentation |\n| `explain_icordebug_interface` | Explain a specific ICorDebug interface |\n| `get_debugging_flow` | Walk through a debugging operation step by step |\n| `list_debugging_concepts` | Browse the concept catalogue by category |\n\n## Things worth knowing\n\n### Breakpoints need portable PDBs\n\nA breakpoint binds through the target's symbols, so the debuggee must be built with portable PDBs\nsitting next to its assembly. A missing or mismatched PDB is the most common reason `set_breakpoint`\nanswers `verified: false` with `No symbols have been loaded for this document`.\n\nDebug builds already do this. For a Release build, or any project that changes the defaults:\n\n```xml\n<PropertyGroup>\n  <DebugType>portable</DebugType>\n  <DebugSymbols>true</DebugSymbols>\n</PropertyGroup>\n```\n\nOptimized code also moves locals out of reach, so `get_variables` is only fully useful with\n`<Optimize>false</Optimize>`.\n\n### macOS: headless environments may need an entitlement\n\nmacOS will not let a debugger take another process's task port unless the target carries\n`com.apple.security.get-task-allow`. A program run through the `dotnet` muxer is fine, because the\nmuxer ships with that entitlement; an apphost produced by `dotnet publish` is ad-hoc signed with no\nentitlements at all.\n\nThe debugger's own side of this needs nothing from you: the debug adapter is started through the\n`dotnet` muxer as well, so it inherits the entitlements that let it debug at all.\n\n**On a desktop session this does not affect you.** Debugging a self-contained publish carrying no\nentitlements is verified to work there.\n\nIt matters in a headless environment, such as a CI runner, and it fails badly when it does: macOS\nrefuses by blocking rather than returning an error, so the debugger stops responding and the call\nnever comes back. If a launch or attach hangs on macOS with no error at all, sign the target and try\nagain:\n\n```bash\ncodesign -s - -f --entitlements get-task-allow.entitlements ./MyApp\n```\n\nwith `get-task-allow.entitlements` containing:\n\n```xml\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<!DOCTYPE plist PUBLIC \"-//Apple//DTD PLIST 1.0//EN\" \"http://www.apple.com/DTDs/PropertyList-1.0.dtd\">\n<plist version=\"1.0\">\n<dict>\n  <key>com.apple.security.get-task-allow</key>\n  <true/>\n</dict>\n</plist>\n```\n\n### What Just My Code changes about stepping\n\n`SHARPDBG_JUST_MY_CODE=false` does not make a step stop in code you have no symbols for. Neither\nsetting does: a step that lands in a module without symbols steps straight back out, because there is\nno source to report a location against. A step through an interpolated string goes through\n`System.Private.CoreLib` and comes back to the next statement of your own method either way.\n\nWhat the setting changes is which modules get their symbols looked for at all. With Just My Code on,\nonly assemblies built by you are searched; with it off, every module is, so a step does surface inside\na dependency you happen to have symbols for. That is what to turn it off for.\n\n### Attaching to other users' processes\n\nA debugger can read and change everything in the process it attaches to, so by default this server\nattaches only to processes belonging to the user it runs as. `attach_to_process` refuses anything\nelse before it looks at the process at all, and `list_dotnet_processes` marks each entry with an\n`owner` of `current_user`, `other_user` or `unknown`.\n\n`unknown` is refused as well. On Windows that is what a system or elevated process looks like, since\nits token cannot be opened, and treating it as your own would make the check decorative wherever the\nlookup does not work.\n\n`SHARPDBG_ALLOW_OTHER_USER_PROCESSES=true` lifts the restriction. The operating system still has its\nown say: on Linux and macOS a normal user cannot attach to another user's process even with this\nenabled, so in practice it matters when the server runs elevated or as root.\n\n### Debugging more than one process\n\nBy default the server debugs one process at a time, and `SHARPDBG_MAX_SESSIONS` raises that. Each\nsession has its own process, breakpoints and stops.\n\n`attach_to_process` and `launch_program` return a `session_id`. While only one session is open you\ncan ignore it, because every tool defaults to the only session. Taking on a second process opens a\nsecond session rather than failing, and from then on `session_id` becomes required: with two\nprocesses open, guessing which one a `continue_execution` was meant for would be worse than asking.\n\n`detach_from_process` leaves the session open and free, so the next attach or launch reuses it rather\nthan taking another slot.\n\nThe default of one is deliberate. Every attach carries a risk of a native crash inside the debugging\nshim, so more sessions means more exposure. What such a crash costs is bounded: each session drives its\nown debug adapter in a process of its own, so the one that crashes takes its session with it and leaves\nthe server and any other session running.\n\n### How failures are reported\n\nEvery tool reports a failure the same way:\n\n```json\n{\n  \"success\": false,\n  \"error\": \"Returned from a call to Continue that was not matched with a stopping event. (0x8013132F)\",\n  \"explanation\": \"The process was already running, so there was nothing to resume. Check get_process_status before continuing.\"\n}\n```\n\n`error` is whatever the debugger said, kept verbatim. `explanation` says what the failure means and\nwhat to do about it, for the `CORDBG_E_*` results the debugger raises: a process that has exited, an\noperation that needs the debuggee stopped, a variable that is not live at this instruction, a frame id\nfrom an earlier stop, another debugger already attached. It is `null` for failures that are not the\ndebugger's, such as invalid arguments.\n\n## Configuration\n\nSet these as environment variables in your client's configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"dotnet-debugger\": {\n      \"command\": \"dotnet\",\n      \"args\": [\"tool\", \"exec\", \"DotnetDebugger.Mcp\", \"--yes\"],\n      \"env\": {\n        \"SHARPDBG_LOG_LEVEL\": \"Debug\"\n      }\n    }\n  }\n}\n```\n\n| Variable | Description | Default |\n|---|---|---|\n| `SHARPDBG_LOG_LEVEL` | `Trace`, `Debug`, `Information`, `Warning`, `Error` or `Critical` | `Information` |\n| `SHARPDBG_MAX_SESSIONS` | Sessions open at once, each debugging its own process | `1` |\n| `SHARPDBG_OPERATION_TIMEOUT_SECONDS` | Bounds attaching, starting, pausing and closing a session. Steps and reads are not bounded | `30` |\n| `SHARPDBG_EVAL_TIMEOUT_MS` | Bounds anything that runs code in the debuggee: `evaluate_expression` and `get_exception_info`. Minimum 100 | `5000` |\n| `SHARPDBG_BREAKPOINT_BIND_TIMEOUT_MS` | How long to wait for a breakpoint to bind before reporting it unverified, minimum 100 | `2000` |\n| `SHARPDBG_JUST_MY_CODE` | Restrict debugging to your own code. See above before turning this off | `true` |\n| `SHARPDBG_ALLOW_OTHER_USER_PROCESSES` | Allow attaching to processes not owned by the current user | `false` |\n| `SHARPDBG_ENABLE_DIAGNOSTICS` | Detailed diagnostic logging | `false` |\n\n## Troubleshooting\n\n**The server does not appear in the client.** Check that the path in the configuration is absolute\nand correct, then fully quit and restart the client. Claude Desktop logs to `~/Library/Logs/Claude/`\non macOS and `%APPDATA%\\Claude\\logs\\` on Windows.\n\n**Attaching fails.** The usual causes are that the process is owned by another user (see above), has\nalready exited, is not a .NET process, or already has a debugger attached. `list_dotnet_processes`\nshows what the server can see and who owns it.\n\n**A breakpoint is not hit.** Check that it came back `verified: true`. If not, the PDB is the first\nthing to look at. If it is verified and still not hit, confirm the line is actually reached and that\nthe file path matches the one the PDB records.\n\n**`list_dotnet_processes` comes back empty on macOS or Linux.** Module enumeration needs permissions\nthere, and the server falls back to detection by process name, which misses programs whose apphost is\nrenamed.\n\n**A launch or attach hangs on macOS with no error.** See the entitlement section above.\n\nTo see what the server is doing, set `SHARPDBG_LOG_LEVEL=Trace` and\n`SHARPDBG_ENABLE_DIAGNOSTICS=true`, or run it directly and watch stderr:\n\n```bash\ndotnet tool exec DotnetDebugger.Mcp --yes\n```\n\n## Development\n\n```bash\ngit clone --recurse-submodules https://github.com/nevse/dotnet-debugger-mcp.git\ncd dotnet-debugger-mcp\ndotnet build\ndotnet test\n```\n\nThe debugger is a submodule at `external/clrdbg`, and the build compiles it and puts the adapter next\nto the server, so there is no separate step. A clone made without submodules fails the build with a\nmessage saying so; `git submodule update --init --recursive` is the fix. To build against a different\nclrdbg checkout - a fork carrying a fix, say - point `ClrdbgSourcePath` at it:\n\n```bash\nClrdbgSourcePath=~/work/clrdbg dotnet build\n```\n\nThe integration tests drive a real debuggee with real breakpoints, so they are slower than the rest\nand are separated by `TestCategory=Integration`.\n\nTo point a client at your working copy instead of the published package:\n\n```bash\nclaude mcp add dotnet-debugger -- dotnet run --project \"$(pwd)/src/SharpDbg.MCP/SharpDbg.MCP.csproj\"\n```\n\n[CONTRIBUTING.md](CONTRIBUTING.md) covers the layout and conventions.\n[docs/RELEASING.md](docs/RELEASING.md) covers cutting a release, including the nuget.org\ntrusted-publishing policy that the workflow depends on but does not show.\n\n## Related projects\n\n- [clrdbg](https://github.com/JaneySprings/clrdbg) — the .NET debugger this server drives\n- [SharpDbg](https://github.com/MattParkerDev/sharpdbg) — the debugger it ran on before the move\n- [ClrDebug](https://github.com/lordmilko/ClrDebug) — ICorDebug API wrapper\n- [Model Context Protocol](https://github.com/modelcontextprotocol) — the specification and SDKs\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 18764,
  "sha": "443b2623ec62ddab7d43f7283b4c9fafcc9f871a393768edc1f2bfbaddab8d0a",
  "repo_slug": "nevse/dotnet-debugger-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_nevse_dotnet_debugger_mcp_3ea27c87/readme"
}