@debugmcp/mcp-debugger
Step-through debugging MCP server for LLMs across ten languages — 29 tools covering breakpoints (line, statement-anchored, function, logpoints), stepping, stack/variable inspection, expression evaluation, buffered program output, launch/attach/restart lifecycle, and a read-only IDE mirror of the live session.
Installation
You can use this package without installation via npx:
npx @debugmcp/mcp-debugger stdio
Or install it globally:
npm install -g @debugmcp/mcp-debugger
Agent skill and pi package
The package ships the mcp-debugger agent skill
at skills/debugging/ (when to debug, the session golden path, root-cause discipline, per-language
references). It is also a pi coding-agent package:
pi install npm:@debugmcp/mcp-debugger installs the skill and an extension
(extensions/mcp-debugger.js) that registers the server with pi's built-in MCP support (pi 0.99 or
later), running the CLI installed alongside it.
Usage
STDIO mode (default)
mcp-debugger stdio
SSE mode
Deprecated: SSE transport is deprecated and will be removed in a future release. Use
mcp-debugger http --port 3001instead.
mcp-debugger sse --port 3001
HTTP mode (recommended)
mcp-debugger http --port 3001
Diagnose your setup
mcp-debugger doctor # report every adapter (informational, always exits 0)
mcp-debugger doctor python go # gate the exit code on the named languages
mcp-debugger doctor --json
doctor probes each adapter's runtime and debug backend in one pass, then prints a
verdict per language plus the fixes for anything that needs attention. Run it first
whenever a language is reported unavailable or a launch fails before your program
starts. With language arguments it exits 1 when any requested language is broken,
missing, disabled, or unknown (and 2 when doctor itself fails); with no arguments
it always exits 0. --timeout <ms> caps each language's probe (default 10000).
See the diagnostics guide for per-language prerequisites and failure signatures.
Batteries-Included Adapters
All language adapters are bundled into the CLI package. No separate installation is needed. The following adapters are included:
- Python (
@debugmcp/adapter-python) - Python debugging via debugpy - Ruby (
@debugmcp/adapter-ruby) - Ruby debugging via rdbg - JavaScript (
@debugmcp/adapter-javascript) - JavaScript/Node.js debugging via js-debug - Rust (
@debugmcp/adapter-rust) - Rust debugging via CodeLLDB - Go (
@debugmcp/adapter-go) - Go debugging via Delve - Java (
@debugmcp/adapter-java) - Java debugging via JDI bridge - .NET (
@debugmcp/adapter-dotnet) - .NET debugging via netcoredbg - C/C++ (
@debugmcp/adapter-cpp) - C/C++ debugging via CodeLLDB - COBOL (
@debugmcp/adapter-cobol) - COBOL debugging via GnuCOBOL + CodeLLDB (a DAP shim adds COBOL-shaped scopes and values) - Dart/Flutter (
@debugmcp/adapter-dart) - Dart and Flutter debugging via the SDK's own debug adapters (dart debug_adapter,flutter debug-adapter) behind a TCP-to-stdio bridge - Mock (
@debugmcp/adapter-mock) - Mock adapter for testing
System Requirements: Node.js 22+ is required to run mcp-debugger. Launching a program also needs that language's toolchain on the machine:
- Python: Python 3.7+ with
debugpy(pip install debugpy) - Ruby: Ruby with the
debuggem (rdbg) - JavaScript/TypeScript: nothing extra — js-debug is bundled
- Rust: the Rust toolchain (rustc/cargo; GNU toolchain on Windows). CodeLLDB itself is vendored — no system LLDB needed
- Go: Go + Delve (
go install github.com/go-delve/delve/cmd/dlv@latest) - Java: JDK 21+ (compile targets with
javac -g) - .NET: netcoredbg + a compatible .NET runtime (Portable PDBs)
- C/C++: none for prebuilt binaries (CodeLLDB vendored); a compiler (g++/clang++) only for lone-source-file launch
- COBOL: GnuCOBOL 3.1.2+ (
cobc:apt install gnucobol3,brew install gnucobol, MSYS2mingw-w64-ucrt-x86_64-gnucobol) for source launch and COBOL-shaped variables; CodeLLDB vendored - Dart/Flutter: the Dart SDK (
darton PATH, orDART_SDK) or Flutter (flutteron PATH, orFLUTTER_ROOT), which bundles Dart; the debug adapter ships with the SDK, nothing is vendored. Flutter runners needflutter --versionrun once so the tool cache is built
CodeLLDB platform note: the CodeLLDB debug engine ships via per-platform optional dependencies (
@debugmcp/codelldb-<platform>) — npm installs exactly the one matching your os/cpu, so Rust, C/C++ and COBOL debugging work out of the box on Windows, macOS, and Linux. Installs with--omit=optionalskip it; pointCODELLDB_PATHat a CodeLLDB binary instead, or use the Docker image.
Attach without a toolchain: only Python (debugpy --listen) and Ruby (rdbg --open) attach direct-connect — the debug engine already runs inside the target, so the debugger host needs no Python or Ruby. JavaScript, Java, .NET, C/C++, COBOL and Dart/Flutter spawn a local adapter for attach (modes.attach: 'spawn') and so do need their toolchain on the debugger host — the Java JDI bridge, for instance, runs locally on the host JDK and connects out over JDWP, and the Dart SDK's adapter connects out to the target's VM-service URI. list_supported_languages reports per-mode availability with reasons.
Useful environment variables
| Variable | Effect |
|---|---|
DEBUG_MCP_NO_REDACT=1 | Disable default-on secret redaction in variable/evaluate/output results |
DEBUG_MCP_VARIABLE_ACCESS=explicit | Least-privilege mode: get_variables requires explicit names: [...] |
DEBUG_MCP_BP_ADDRESSING=line|assert|content | Breakpoint addressing mode (default content: statement anchors + content assertions) |
CODELLDB_PATH | Path to a CodeLLDB binary when the platform packages are unavailable (see note above) |
CPP_MSVC_BEHAVIOR=warn|error|continue | What to do when a C/C++ target looks MSVC-built (partial PDB fidelity) |
COBC_PATH | Pin the GnuCOBOL compiler (cobc) when it is not on PATH or in a known install directory |
DART_SDK | Dart SDK root (or its bin/dart) when dart is not on PATH; DART_PATH is an alias |
FLUTTER_ROOT | Flutter SDK root when flutter is not on PATH — its bundled Dart is used when no standalone SDK is found; FLUTTER_PATH is an alias |
MCP_HTTP_STALE_SESSION_MS | HTTP mode: reap a crash-abandoned MCP session that never opened an SSE stream after this idle time (default 30 min) |
MCP_HTTP_STREAM_LOST_SESSION_MS | HTTP mode: reap a session whose SSE stream dropped and never returned after this idle time (default 2 min) — releases a dead client's paused attach target |
MCP_HTTP_ALLOWED_HOSTS | HTTP and (deprecated) SSE modes: comma-separated Host (and browser Origin) hostnames to accept besides localhost, 127.0.0.1, [::1] — only when another access control fronts the server; same as repeating --allowed-host |
MCP_HTTP_BIND | HTTP and (deprecated) SSE modes: IP address to listen on (default 127.0.0.1, loopback only); same as --bind. The Docker image sets 0.0.0.0 so a published port works. An empty value refuses to start |
Check Rust binary compatibility
mcp-debugger check-rust-binary <path-to-binary>
mcp-debugger check-rust-binary --json <path-to-binary>
Analyzes a Rust executable to determine whether it was built with the GNU or MSVC toolchain and reports CodeLLDB debugging compatibility. Use --json for machine-readable output.
Options
Server options (stdio, sse, http)
-l, --log-level <level>- Set log level (error, warn, info, debug; default: info)--log-file <path>- Log to file instead of console
SSE and HTTP options
-p, --port <number>- Port for SSE or HTTP mode (default: 3001)--bind <address>- IP address to listen on (default:127.0.0.1, loopback only; orMCP_HTTP_BIND).0.0.0.0listens on every interface and is reachable from other machines — pair it with--allowed-host <name>for the name those clients dial, and front the server with another access control.localhostmeans127.0.0.1; hostnames and an empty value are refused.GET /healthreports the bound address and port underlistening.
HTTP options
--allowed-host <host>- AdditionalHost/Originhostname to accept (repeatable; orMCP_HTTP_ALLOWED_HOSTS, comma-separated). Implies another access control fronts this server. No wildcard. Default:localhost,127.0.0.1,[::1]. The deprecatedssecommand takes the same option.
doctor options
[languages...]- Languages to check and gate the exit code on (default: report all, exit 0)--json- Emit a machine-readable report--timeout <ms>- Per-language probe timeout in milliseconds (default: 10000)
check-rust-binary options
--json- Emit a machine-readable report
Documentation
See the main repository for full documentation.
License
MIT