netcoredbg-mcp

MCP (Model Context Protocol) server for debugging C#/.NET applications using netcoredbg.

Debug .NET apps from AI agents — set breakpoints, step through code, inspect variables, and evaluate expressions without requiring VS Code or any IDE.

Quick Links

Get Started: Install · Configure · First Debug Session
Reference: Tools · Troubleshooting · Architecture

Highlights

Feature	Description
🚀 Standalone	No IDE required — works directly with AI agents
🔧 Full DAP	Complete Debug Adapter Protocol via netcoredbg
🏗️ Pre-build	Build before debug with `pre_build: true`
🎯 Smart Resolution	Auto-resolves `.exe` → `.dll` for .NET 6+
⚠️ Version Check	Detects dbgshim.dll mismatches automatically

Critical Notes

Warning

dbgshim.dll Version Compatibility

The dbgshim.dll in your netcoredbg folder MUST match the major version of the .NET runtime you're debugging. This is an undocumented Microsoft requirement. Mismatch causes:

E_NOINTERFACE (0x80004002) errors
Empty call stacks
Failed variable inspection

Target Runtime	Required dbgshim.dll Source
.NET 6.x	`C:\Program Files\dotnet\shared\Microsoft.NETCore.App\6.0.x\dbgshim.dll`
.NET 7.x	`C:\Program Files\dotnet\shared\Microsoft.NETCore.App\7.0.x\dbgshim.dll`
.NET 8.x	`C:\Program Files\dotnet\shared\Microsoft.NETCore.App\8.0.x\dbgshim.dll`
.NET 9.x	`C:\Program Files\dotnet\shared\Microsoft.NETCore.App\9.0.x\dbgshim.dll`

# Example: Setup for .NET 6 debugging
copy "C:\Program Files\dotnet\shared\Microsoft.NETCore.App\6.0.36\dbgshim.dll" "D:\Bin\netcoredbg\"

Tip

This MCP server automatically detects mismatches and warns you during start_debug.

Important

Prefer start_debug over attach_debug

attach_debug has significant upstream limitations in netcoredbg — stack traces and variable inspection may be incomplete or empty.

Installation

Requirements

Python 3.10+
netcoredbg
.NET SDK (for the apps you're debugging)

Install the MCP Server

# Install from PyPI (recommended)
uv pip install netcoredbg-mcp

# Or with pip
pip install netcoredbg-mcp

Install from Source (Development)

git clone https://github.com/thebtf/netcoredbg-mcp.git
cd netcoredbg-mcp
uv sync

Install netcoredbg

Download from Samsung/netcoredbg releases and extract to D:\Bin\netcoredbg\

Configuration

Environment Variable

Set NETCOREDBG_PATH in your PowerShell profile (%USERPROFILE%\Documents\PowerShell\Microsoft.PowerShell_profile.ps1):

$env:NETCOREDBG_PATH = "D:\Bin\netcoredbg\netcoredbg.exe"

Base Server Configuration

All clients use this same server definition:

{
  "netcoredbg": {
    "command": "netcoredbg-mcp",
    "args": ["--project-from-cwd"],
    "env": {
      "NETCOREDBG_PATH": "D:\\Bin\\netcoredbg\\netcoredbg.exe"
    }
  }
}

Running from Source (Development)

If running from cloned repository instead of PyPI:

{
  "netcoredbg": {
    "command": "uv",
    "args": ["run", "--project", "D:\\Dev\\netcoredbg-mcp", "netcoredbg-mcp", "--project-from-cwd"],
    "env": {
      "NETCOREDBG_PATH": "D:\\Bin\\netcoredbg\\netcoredbg.exe"
    }
  }
}

[!IMPORTANT] Use uv run --project NOT uv --directory. The --directory flag changes CWD, breaking --project-from-cwd.

Client Setup

CLI Agents

Claude Code

claude mcp add --scope user netcoredbg -- netcoredbg-mcp --project-from-cwd

Verify: claude mcp list

Codex CLI (OpenAI)

Config: %USERPROFILE%\.codex\config.toml

[mcp_servers.netcoredbg]
command = "netcoredbg-mcp"
args = ["--project-from-cwd"]

[mcp_servers.netcoredbg.env]
NETCOREDBG_PATH = "D:\\Bin\\netcoredbg\\netcoredbg.exe"

Or via CLI: codex mcp add netcoredbg -- netcoredbg-mcp --project-from-cwd

Gemini CLI (Google)

Config: %USERPROFILE%\.gemini\settings.json

{
  "mcpServers": {
    "netcoredbg": {
      "command": "netcoredbg-mcp",
      "args": ["--project-from-cwd"],
      "env": {
        "NETCOREDBG_PATH": "D:\\Bin\\netcoredbg\\netcoredbg.exe"
      }
    }
  }
}

Cline

Config: Open Cline → MCP Servers icon → Configure → "Configure MCP Servers"

{
  "mcpServers": {
    "netcoredbg": {
      "command": "netcoredbg-mcp",
      "args": ["--project-from-cwd"],
      "env": {
        "NETCOREDBG_PATH": "D:\\Bin\\netcoredbg\\netcoredbg.exe"
      }
    }
  }
}

Roo Code

Config: %USERPROFILE%\.roo\mcp.json or .roo\mcp.json in project

{
  "mcpServers": {
    "netcoredbg": {
      "command": "netcoredbg-mcp",
      "args": ["--project-from-cwd"],
      "env": {
        "NETCOREDBG_PATH": "D:\\Bin\\netcoredbg\\netcoredbg.exe"
      }
    }
  }
}

Desktop Apps

Claude Desktop

Config: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "netcoredbg": {
      "command": "netcoredbg-mcp",
      "args": ["--project-from-cwd"],
      "env": {
        "NETCOREDBG_PATH": "D:\\Bin\\netcoredbg\\netcoredbg.exe"
      }
    }
  }
}

IDE Extensions

Cursor

Config: %USERPROFILE%\.cursor\mcp.json

{
  "mcpServers": {
    "netcoredbg": {
      "command": "netcoredbg-mcp",
      "args": ["--project-from-cwd"],
      "env": {
        "NETCOREDBG_PATH": "D:\\Bin\\netcoredbg\\netcoredbg.exe"
      }
    }
  }
}

Windsurf

Config: %USERPROFILE%\.codeium\windsurf\mcp_config.json

{
  "mcpServers": {
    "netcoredbg": {
      "command": "netcoredbg-mcp",
      "args": ["--project-from-cwd"],
      "env": {
        "NETCOREDBG_PATH": "D:\\Bin\\netcoredbg\\netcoredbg.exe"
      }
    }
  }
}

VS Code + Continue

Config: %USERPROFILE%\.continue\config.json

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "uv",
          "args": ["run", "--project", "D:\\Dev\\netcoredbg-mcp", "netcoredbg-mcp", "--project-from-cwd"],
          "env": {
            "NETCOREDBG_PATH": "D:\\Bin\\netcoredbg\\netcoredbg.exe"
          }
        }
      }
    ]
  }
}

Project-Scoped Config

.mcp.json (in project root)

Add to your .NET project root for automatic loading:

{
  "mcpServers": {
    "netcoredbg": {
      "command": "uv",
      "args": ["run", "--project", "D:\\Dev\\netcoredbg-mcp", "netcoredbg-mcp"],
      "env": {
        "NETCOREDBG_PATH": "D:\\Bin\\netcoredbg\\netcoredbg.exe",
        "NETCOREDBG_PROJECT_ROOT": "${workspaceFolder}"
      }
    }
  }
}

[!NOTE] With project-scoped config, use NETCOREDBG_PROJECT_ROOT instead of --project-from-cwd.

First Debug Session

Typical Workflow

1. start_debug     → Launch program under debugger
2. add_breakpoint  → Set breakpoints in source files
3. continue        → Run until breakpoint hit
4. get_call_stack  → Inspect where you stopped
5. get_variables   → Examine local variables
6. step_over       → Step through code
7. stop_debug      → End session

Example: start_debug with Pre-build

start_debug(
    program="/path/to/MyApp.exe",      # Auto-resolves to .dll for .NET 6+
    pre_build=True,                     # Build before launching
    build_project="/path/to/MyApp.csproj",
    build_configuration="Debug",
    stop_at_entry=False
)

Smart .exe → .dll Resolution

For .NET 6+ applications (WPF, WinForms, Console), the SDK creates:

App.exe — Native host launcher
App.dll — Actual managed code

Debugging .exe causes a "deps.json conflict" error. This MCP server automatically resolves .exe to .dll when a matching .dll and .runtimeconfig.json exist.

Available Tools

Debug Control

Tool	Description
`start_debug`	Recommended. Launch program with full debug support. Supports `pre_build`.
`attach_debug`	Attach to running process ⚠️ Limited functionality
`stop_debug`	Stop the debug session
`continue_execution`	Continue program execution
`pause_execution`	Pause program execution
`step_over`	Step over to next line
`step_into`	Step into function call
`step_out`	Step out of current function
`get_debug_state`	Get current session state

start_debug Parameters

Parameter	Type	Description
`program`	string	Path to .exe or .dll (auto-resolved)
`cwd`	string?	Working directory
`args`	list?	Command line arguments
`env`	dict?	Environment variables
`stop_at_entry`	bool	Stop at program entry point
`pre_build`	bool	Build before launching
`build_project`	string?	Path to .csproj (required if pre_build)
`build_configuration`	string	"Debug" or "Release"

Breakpoints

Tool	Description
`add_breakpoint`	Add breakpoint with optional condition and hit count
`remove_breakpoint`	Remove a breakpoint by file and line
`list_breakpoints`	List all active breakpoints
`clear_breakpoints`	Clear all breakpoints (optionally by file)

Inspection

Tool	Description
`get_threads`	Get all threads with their states
`get_call_stack`	Get call stack for a thread
`get_scopes`	Get variable scopes for a stack frame
`get_variables`	Get variables in a scope
`evaluate_expression`	Evaluate expression in current context
`get_exception_info`	Get exception details when stopped on exception
`get_output`	Get debug console output

MCP Resources

Resource URI	Description
`debug://state`	Current session state
`debug://breakpoints`	All active breakpoints
`debug://output`	Debug console output buffer

Troubleshooting

Empty call stack / E_NOINTERFACE (0x80004002)

Symptom: get_call_stack returns empty array or error containing 0x80004002.

Cause: dbgshim.dll version mismatch between netcoredbg and target runtime.

Solution:

Check the warning from start_debug — it shows exact versions
Copy the correct dbgshim.dll:

# Find your .NET runtime versions
dir "C:\Program Files\dotnet\shared\Microsoft.NETCore.App\"

# Copy matching version (e.g., for .NET 6 app)
copy "C:\Program Files\dotnet\shared\Microsoft.NETCore.App\6.0.36\dbgshim.dll" "D:\Bin\netcoredbg\"

deps.json conflict error

Symptom: Launch fails with "assembly has already been found but with a different file extension".

Cause: Debugging .exe instead of .dll for a .NET 6+ app.

Solution: Should be auto-resolved. If not, explicitly pass the .dll path:

program: "App.dll"  # instead of "App.exe"

Program not found with pre_build

Symptom: start_debug with pre_build: true fails saying program doesn't exist.

Cause: Old version that validated path before building.

Solution: Update to latest version. Path validation is now deferred until after build.

Breakpoints not hitting

Symptom: Breakpoints are set but never triggered.

Possible causes:

Wrong configuration (Release instead of Debug)
Source mismatch (binary doesn't match source)
JIT optimization affecting line mappings

Solution: Use pre_build: true to ensure fresh Debug build.

Attach mode: empty stack traces

Symptom: After attaching to running process, get_call_stack returns empty.

Cause: netcoredbg doesn't support justMyCode in attach mode (upstream limitation).

Solution: Use start_debug instead. If you must attach, expect limited functionality.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     MCP Server (Python)                          │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌────────────────────────┐ │
│  │  MCP Tools   │  │  DAP Client  │  │   Session Manager      │ │
│  │  (20 tools)  │←→│  (protocol)  │←→│   (state + validation) │ │
│  └──────────────┘  └──────┬───────┘  └────────────────────────┘ │
│                           │                                      │
│  ┌──────────────┐         │          ┌────────────────────────┐ │
│  │ Version      │         │          │   Build Manager        │ │
│  │ Checker      │         │          │   (pre_build support)  │ │
│  └──────────────┘         │          └────────────────────────┘ │
└───────────────────────────┼─────────────────────────────────────┘
                            │ stdio (JSON-RPC)
                     ┌──────▼──────┐
                     │ netcoredbg  │
                     │ (DAP Server)│
                     └─────────────┘

How It Works

MCP Layer — Exposes debugging tools via Model Context Protocol
Session Manager — Manages debug session state, validates paths, handles events
DAP Client — Communicates with netcoredbg via Debug Adapter Protocol (JSON-RPC over stdio)
Build Manager — Optionally builds project before debugging (pre_build feature)
Version Checker — Validates dbgshim.dll compatibility with target runtime

Command Line Options

Option	Description
`--project PATH`	Explicit project root path
`--project-from-cwd`	Auto-detect project from CWD

Environment Variables

Variable	Description
`NETCOREDBG_PATH`	Required. Path to netcoredbg executable
`NETCOREDBG_PROJECT_ROOT`	Project root path (alternative to `--project`)
`LOG_LEVEL`	Logging level: DEBUG, INFO, WARNING, ERROR
`LOG_FILE`	Path to log file for diagnostics

Limitations

Single session — Only one debug session at a time (by design)
Attach mode — Limited functionality due to netcoredbg upstream limitation
dbgshim version — Must manually match version to target runtime
Windows focus — Primary development/testing on Windows (Linux/macOS may work)

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 22 Commits
.github/workflows		.github/workflows
src/netcoredbg_mcp		src/netcoredbg_mcp
test-app		test-app
tests		tests
.gitignore		.gitignore
.mcp.json.example		.mcp.json.example
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
netcoredbg-mcp.sln		netcoredbg-mcp.sln
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

netcoredbg-mcp

Quick Links

Highlights

Critical Notes

Installation

Requirements

Install the MCP Server

Install netcoredbg

Configuration

Environment Variable

Base Server Configuration

Client Setup

CLI Agents

Desktop Apps

IDE Extensions

Project-Scoped Config

First Debug Session

Typical Workflow

Example: start_debug with Pre-build

Smart .exe → .dll Resolution

Available Tools

Debug Control

Breakpoints

Inspection

MCP Resources

Troubleshooting

Architecture

How It Works

Command Line Options

Environment Variables

Limitations

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages