mcp-netcoredbg

MCP server for .NET debugging via netcoredbg.

Enables AI agents (Claude, etc.) to set breakpoints, step through code, and inspect variables in .NET applications.

Architecture

Tools

Session Management (NEW in v2.0)

Launch & Attach

Breakpoints

Execution Control

Inspection

Note: All tools accept an optional sessionId parameter to target a specific session. If omitted, the default session is used.

Multi-Session Debugging (v2.0)

Version 2.0 introduces support for multiple simultaneous debug sessions. This allows you to debug multiple .NET applications concurrently - for example, an API and a background worker.

Auto-Generated Session IDs

When you launch a debug session without specifying a sessionId, one is automatically derived from the project/program name:

• TopServer.Service.Api → session ID: api

• TopServer.Service.Worker → session ID: worker

• MyApp.Web → session ID: web

• Custom: specify sessionId parameter explicitly

Example: Debugging API + Worker Simultaneously

Session Management Commands

Backward Compatibility

If you only use one session, the behavior is unchanged from v1.x - no sessionId parameter needed.

Method Invocation (invoke)

The invoke tool lets you run a specific method from a .NET assembly without launching the full application. This is useful for:

• Testing individual methods in isolation

• Running utility functions

• Debugging specific code paths without going through the whole app

Parameters

Examples

Static method:

Instance method with constructor arguments:

With debugging (breakpoints supported):

Features

• Static methods: Just provide type, method, and args

• Instance methods: Automatically constructs the type (provide ctorArgs if needed)

• Auto ILogger injection: ILogger<T> parameters are automatically resolved

• Async support: Automatically awaits Task-returning methods

• Console capture: Captures Console.WriteLine output

• Log capture: Captures ILogger calls made during execution

• Rich errors: On failure, shows available constructors/methods to help you fix the call

Output Format

The tool returns a structured JSON result:

On error, it provides helpful diagnostics:

Hot Reload Debugging (launch_watch)

The launch_watch tool enables debugging with hot reload support via dotnet watch. When you make code changes, the app automatically restarts and the debugger reconnects - preserving your breakpoints.

Parameters

Examples

Basic usage:

With launch profile (recommended for ASP.NET apps):

The launch profile is important for ASP.NET applications as it sets:

• ASPNETCORE_ENVIRONMENT (e.g., Development)

• applicationUrl (e.g., https://localhost:7179)

• Other environment variables needed for proper operation

How It Works

1. Starts dotnet watch run with the specified project

2. Waits for the app to build and start

3. Automatically attaches the debugger to the running process

4. When you edit code and save, dotnet watch rebuilds and restarts

5. The debugger detects the restart and reconnects automatically

6. Breakpoints are preserved across restarts

Stopping Hot Reload Mode

Use stop_watch to cleanly terminate both the debugger and the dotnet watch process.

Status Information

Use status to see hot reload specific information:

• Watch process PID

• Child app PID

• Whether the debugger is currently reconnecting

Prerequisites

• netcoredbg installed and in PATH

• Node.js 18+

• .NET SDK 8.0+ (for building the harness and target applications)

Installation

Usage with Claude Code

Quick install:

Or manually add to your Claude Code MCP settings:

Security

This tool launches and controls a debugger. By design, it can:

• Execute arbitrary .NET applications

• Evaluate expressions within the debugged process

• Inspect memory and variables

Only use this with code you trust. Do not debug untrusted applications.

Example Session

Full Application Debugging

1. Build your .NET app with debug symbols: dotnet build --configuration Debug

2. Launch debugger: launch with the DLL path

3. Set breakpoints: set_breakpoint at file:line

4. Continue/step through code

5. Inspect variables with scopes and variables

6. Evaluate expressions with evaluate

7. Terminate when done

Method Invocation (Quick Testing)

1. Build the target assembly: dotnet build

2. Use invoke with the type and method name

3. If it fails, check the error for available constructors/methods

4. For debugging: set breakpoints first, then use invoke with debug: true

Agent Guidelines

When using this MCP server as an AI agent:

Choosing Between launch and invoke

• Use invoke when you want to test a specific method in isolation

• Use launch when you need to run the full application or debug complex scenarios

Using invoke Effectively

1. Start simple: Try without ctorArgs first - the harness will use parameterless constructors or auto-inject ILogger<T>

2. Handle errors iteratively: If invocation fails, the error response includes available methods/constructors. Use this to correct your call.

3. For debugging specific methods:

   1. Set breakpoints in the source files first 2. Call invoke with debug: true 3. Use continue/step_over/step_into to navigate 4. Use output to see the final result

4. Arguments are JSON: Pass args as a JSON array. The harness handles type conversion:

   • Strings: "hello"

   • Numbers: 42, 3.14

   • Booleans: true, false

   • Null: null

   • Objects: {"name": "Alice", "age": 30}

Common Patterns

Testing a utility method:

Testing with constructor injection:

Debugging a failing method:

License

MIT