aspnetcore-debugger-mcp

ASP.NET Core Debugging MCP Server


The cross-platform .NET debugging MCP — runs on Linux, macOS, and Windows.

<!-- mcp-name: io.github.magna-nz/aspnetcore-debugger-mcp -->

       

An MIT-licensed MCP server that lets an AI agent (Claude, etc.) debug your .NET / ASP.NET Core app — netcoredbg bundled for every platform, nothing extra to install.

Instead of "I think the bug is around line 42, try this", the agent runs your code, pauses it, reads the actual runtime values, mutates state to test a fix, and answers grounded in what it actually saw.

Contents

• See it in action — 5 conversations showing the agent at work
• How it works — architecture diagram
• Use it in 3 steps — install + register with Claude
• Platforms — supported OS / architecture matrix
• Tools (27) — full tool surface grouped by purpose
• How this compares — vs. other .NET / DAP MCPs
• Docs — install, examples, tool reference, limits
• License

See it in action

Why is my EF Core query returning empty?

You

GET /users/active returns [], but I know there are active users in the DB. What's the query actually doing?

Claude

I'll pause inside UserRepository.GetActiveAsync and read what EF Core actually sent. ``sql SELECT u.* FROM Users AS u WHERE u.IsActive = 1 AND u.TenantId = @__tenantId_0 @__tenantId_0 = 0 ` The SQL is correct; the parameter is wrong. TenantId = 0, but your tenants start at 1. ICurrentUser.TenantId is being read in the repository constructor — before the request scope resolves it. Fix: read the tenant inside the query (or apply it via HasQueryFilter with IHttpContextAccessor`) instead of capturing it at construction.

Why is my JWT auth returning 401?

You

/admin/users is 401-ing for Anna, but her token looks valid to me. What does the auth handler actually see?

Claude

I'll break inside JwtBearerHandler.HandleAuthenticateAsync after her request lands. `` Token signature: ✓ valid Claims built: name : anna role : User iss : https://auth.staging.example aud : app-api exp : 2026-05-26T14:12:00Z (not expired) ` The token validates fine — but the claim is role=User. Your endpoint is [Authorize(Roles="Admin")]`. So the 401 is correct: Anna isn't actually an admin yet upstream. Either her IdP record needs updating, or this policy is wrong.

Test a fix without restarting

You

I think capping discount at 100 fixes the bug. Test that hypothesis without me touching the code.

Claude

I'll pause inside ApplyDiscount on the next checkout and mutate discount in place. `` Paused at PricingService.cs:47 discount = 250 ← bug: two promos stacked Set discount = 100, resumed. Result: subtotal = $400 final = $300 refund-service complaints: 0 ` Capping at 100 unblocks the flow downstream. Hypothesis confirmed — time to make the edit for real and decide where the cap belongs (ApplyDiscount itself, or upstream in PromoEngine`).

My app is hung — what's actually blocking?

You

/reports hangs forever in staging. Attach and tell me why.

Claude

Attached. Ran hang_analyze. `` Thread 12 (HTTP request) → blockedOnTask at ReportService.cs:38 Task.Wait() on T#14 Thread 14 (worker) → blockedOnMonitor at SqlConnectionPool.cs:91 waiting for SqlConnection (pool max=5, in-use=5) ` Classic sync-over-async deadlock. Thread 12 calls .Wait() on a task that itself needs to open another SqlConnection from a fully-held pool. The connection it's holding can't be released until the task completes; the task can't proceed until a connection frees up. Fix: await all the way down in ReportService`, or don't hold a connection across the awaited call.

Where is a slow request actually spending its time?

You

GET /order/42 takes 800ms. I don't want to set breakpoints all over — just show me where the time is going.

Claude

I'll auto-instrument your order pipeline and fire the request. Each entry logs the timestamp + arguments, then resumes — the code runs near-normal speed. `` [+ 4ms] → OrderController.GetOrder() id=42 [+ 6ms] --→ OrderService.LookupOrder() id=42 [+ 9ms] ----→ OrderRepository.FetchById() id=42 [+ 14ms] ------→ SqlClient.ExecuteQuery() sql="SELECT * FROM orders WHERE id=42" [+ 287ms] ----→ EnrichmentService.Enrich() raw="rows(...)" [+ 781ms] ------→ HttpClient.PostAsync() url="https://crm.internal/enrich" ` Time is in the CRM enrichment HTTP call — 500ms inside HttpClient.PostAsync. DB itself was 5ms. Worth caching EnrichmentService.Enrich` or moving it off the request path.

More examples →

How it works

Claude (MCP client)
   │  MCP  (stdio / JSON-RPC)
   ▼
aspnetcore-debugger-mcp        ← this server
   │  DAP  (Debug Adapter Protocol)
   ▼
netcoredbg                     ← Samsung's MIT-licensed .NET debugger, child process
   │  ICorDebug
   ▼
target .NET process

A protocol bridge with agent-friendly composites on top — exception_autopsy, stack_explore, hang_analyze, and the trace tools — that bundle multiple DAP requests into a single tool call.

Use it in 3 steps

1. Install the tool — needs the .NET 10 SDK.

   dotnet tool install -g AspNetCoreDebuggerMcp --prerelease

The package bundles prebuilt netcoredbg for linux-x64, linux-arm64, win-x64, osx-x64, and osx-arm64 — no separate install needed.

1. Register with Claude — either the quick CLI command:

   claude mcp add aspnetcore-debugger -- aspnetcore-debugger-mcp

…or edit .mcp.json (project-scoped) / ~/.claude.json (global) / claude_desktop_config.json (Claude Desktop) directly: ``json { "mcpServers": { "aspnetcore-debugger": { "command": "aspnetcore-debugger-mcp" } } } ``

1. Just chat with Claude. /mcp confirms it's connected. From there, describe what you want — "why does this endpoint return null" — and the agent picks the right tools.

Full install + troubleshooting →

Platforms

Bundled netcoredbg binary is selected at runtime — no per-platform install dance.

| OS | Architectures | Status | |---|---|---| | Linux | x64, arm64 | ✅ Supported (Samsung prebuilt) | | macOS | Intel (x64), Apple Silicon (arm64) | ✅ Supported (arm64 built by us, since Samsung doesn't ship one) | | Windows | x64 | ✅ Supported (Samsung prebuilt) |

Requires the .NET 10 SDK on the host. The MCP server itself is a cross-platform .NET global tool — same install command everywhere.

Tools (27)

| Category | Tools | What it's for | |---|---|---| | Session | debug_launch, debug_attach, debug_disconnect, debug_state | Start, attach to, or stop a debug session | | Execution | debug_continue, debug_pause, debug_step, breakpoint_wait | Drive the debuggee and wait for it to stop | | Breakpoints | breakpoint_set, breakpoint_set_function, breakpoint_set_exception, breakpoint_set_data, breakpoint_remove, breakpoint_list | Line, function, exception, and data breakpoints | | Inspection | threads_list, stacktrace_get, variables_get, variables_set, evaluate, stack_explore | Examine and mutate program state | | Exception Autopsy | exception_autopsy | One call: exception chain + top frames + locals + source snippet | | Hang / Deadlock | hang_analyze | Auto-pause, classify each thread's blocking pattern (Monitor / Task / Semaphore / async / …) | | Request Tracing | trace_start, trace_get, trace_stop | Server-side request tracing — auto-instrument a call chain and capture arguments at every entry | | Process I/O | process_read_output | Drain the debuggee's stdout/stderr | | Health | debugger_health | Quick check that netcoredbg loaded and the bundled binary is reachable |

Full tool reference with parameters →

How this compares

| Project | License | Platforms | Approach | .NET | |---|---|---|---|---| | aspnetcore-debugger-mcp (this) | MIT | Linux + macOS + Windows | netcoredbg via DAP, ASP.NET-focused composites (request tracing, hang analysis) | Native, .NET 10 | | debug-mcp | AGPL-3.0 | Linux only (Win/macOS planned) | ICorDebug direct, Roslyn code nav | Native, .NET 10 | | mcp-debugger | — | Cross-platform | DAP | Via external debugger | | dap-mcp | — | Cross-platform | DAP | Via external debugger | | LLDB MCP | NCSA | Cross-platform | Native LLDB | No |

Different sweet spots: this project is the MIT, cross-platform option, with ASP.NET-flavoured composites on top of a DAP. debug-mcp goes deeper into runtime internals via ICorDebug but is Linux-only and AGPL today.

Docs

• Install & configure — 3 steps, both Claude Code & Desktop, troubleshooting
• What you can do with it — 7 things you can ask Claude to do for you
• Full tool reference — every parameter on every tool
• Known limits — when not to use this tool, adapter & tracing limits
• macOS Apple Silicon — building netcoredbg
• Contributing — repo layout, tests, dev loop

License

MIT — see LICENSE. Built on netcoredbg (MIT) and the ModelContextProtocol SDK (MIT).