mcp-debugger

mcp-debugger

A headless, agentic debugger over MCP — let your AI agents debug running programs in ten languages.

🎯 Overview

mcp-debugger is a Model Context Protocol (MCP) server that exposes step-through debugging as structured tool calls. It lets AI agents set breakpoints, inspect variables, evaluate expressions, and step through running programs across ten languages — driving real language debuggers through the Debug Adapter Protocol (DAP).

No IDE required. mcp-debugger runs anywhere Node.js runs: CI runners, Docker containers, Kubernetes pods, SSH boxes, and the sandboxes that cloud coding agents live in. It's the debugger for where IDEs can't go.

When to use mcp-debugger vs an IDE-bound debug server

Microsoft's DebugMCP exposes VS Code's debugger over MCP and is a good choice when your agent works *inside* a running VS Code. The two projects make different structural trade-offs:

If your agent runs in a terminal, a pipeline, or a cloud sandbox — or needs to attach to a process on another machine — you want mcp-debugger.

🆕 v0.26.0 — Dart and Flutter debugging lands (the SDK's own debug adapters: Dart programs and tests, Flutter apps and tests on desktop, web, Android and the iOS simulator, hot reload and hot restart), every stop answer carries a snapshot of the exception, top frames and locals (a repeated stop reports only what changed), `wait_for_stop` blocks until the next stop instead of polling, and one-call failing-test debugging for pytest pauses at the failing assert with no breakpoint set. Also new: one launch contract for every language (a short hold, then pending: true), dryRunSpawn as a side-effect-free query, hot_reload (replacing redefine_classes, kept as a deprecated alias), Streamable HTTP spec conformance checked in CI, and host/Docker build caches that no longer collide. See the CHANGELOG for the full release history.

✨ Key Features

• 🌐 Multi-language support – Clean adapter pattern for any language
• 🐍 Python debugging via debugpy – Full DAP protocol support
• 💎 Ruby debugging via rdbg – Launch and attach workflows, including remote attach to containers and Kubernetes pods
• 🟨 JavaScript (Node.js) debugging via js-debug – VSCode's proven debugger
• 🦀 Rust debugging via CodeLLDB – Debug Rust & Cargo projects (Linux/macOS; Windows needs the GNU toolchain — see Rust on Windows)
• 🐹 Go debugging via Delve – Full DAP support for Go programs
• ☕ Java debugging via JDI bridge – Launch and attach modes with JDK 21+
• 🔷 .NET/C# debugging via netcoredbg – Debug .NET applications with full DAP support
• ⚙️ C/C++ debugging via CodeLLDB – Launch prebuilt binaries or lone source files (auto-compiled), attach by PID; core dumps and gdbserver/rr targets via config pass-through
• 🧮 COBOL debugging via GnuCOBOL + CodeLLDB – Launch .cob/.cbl sources (auto-compiled with cobc) or prebuilt executables, attach by PID; WORKING-STORAGE / LOCAL-STORAGE / LINKAGE scopes with DISPLAY, COMP, COMP-3 and 88-level values decoded, breakpoints in copybooks, statement-granular stepping, and a pause on libcob runtime errors (the S0C7/SSRANGE analogues) — built for mainframe-to-GnuCOBOL migrations (guide)
• 🐦 Dart/Flutter debugging via the SDK's own debug adapters – Launch Dart programs and package:test files (dart debug_adapter) or Flutter apps and tests (flutter debug-adapter), the runner auto-detected from pubspec.yaml and the program path; attach to a running VM by service URI or service-info file; conditional breakpoints, logpoints, Unhandled/All exception filters, noDebug. Nothing is vendored — the Dart or Flutter SDK on the machine is the debugger. Flutter runs on Windows, macOS and Linux desktops, in Chrome or Edge, on Android emulators and devices and on the iOS simulator, with hot_reload and a hot restart_debugging once the app has started; an app on an Android device attaches by deviceId alone (guide)
• 🧪 Mock adapter for testing – Test without external dependencies
• 🛰️ Out-of-IDE & remote attach – Attach over host/port to a process on another machine or inside a container (Python via debugpy, Ruby via rdbg, JavaScript via the V8 inspector, Java via JDWP, Dart/Flutter via the VM-service URI) with source-path mapping, or by PID for native code (C/C++, COBOL) and for a local Node.js process, whose inspector mcp-debugger opens for you (JavaScript). Python and Ruby attach *direct-connect* — the debug engine already runs inside the target, so no local Python or Ruby is needed; JavaScript, Java, .NET, C/C++, COBOL and Dart/Flutter spawn a local adapter instead; of those, only Java (a JDK), .NET (netcoredbg) and Dart/Flutter (the Dart or Flutter SDK, whose own debug adapter does the work) need a toolchain you install, since the JavaScript, C/C++ and COBOL debug engines ship with the package. list_supported_languages reports per-mode availability with reasons
• 🎯 Breakpoints that survive edits – Address by content (statement: "total = sum(prices)"), by symbol (function: "main"), or assert line content with expectedContent; anchors re-resolve across restart_debugging and weak matches warn loudly
• 🪵 Logpoints – set_breakpoint with logMessage: "x={x}" streams interpolated values into get_output without pausing — prod-safe value watching on hot paths
• 🧰 Full breakpoint lifecycle – list_breakpoints / remove_breakpoint / clear_breakpoints work live mid-run; restart_debugging relaunches with the same config and re-applies everything in one call
• 📡 Buffered program output – get_output returns debuggee stdout/stderr with a cursor, and each session exposes its transcript as a subscribable MCP resource
• 💥 Crash-state debugging by default – Launch sessions pause on uncaught exceptions with stack and locals live (breakOnExceptions; exception class/message surfaced via lastStop)
• 🪞 Read-only IDE mirror – expose_session opens a loopback, token-gated DAP endpoint so a human's IDE can inspect the agent's live session without taking control
• ☸️ Kubernetes debugging – port-forward attach for interpreted runtimes, kubectl debug --target + attach-by-PID for native processes (recipe, turnkey manifests)
• 🔌 STDIO and Streamable HTTP transports – Works with any MCP client
• 📦 Zero-runtime dependencies – Self-contained bundles via esbuild + tsup
• ⚡ npx ready – Run directly with npx @debugmcp/mcp-debugger - no installation needed
• 🐳 Docker and npm packages – Deploy anywhere
• 🤖 Built for AI agents – Structured JSON responses for easy parsing
• 🔒 Secret redaction on by default – Credential-shaped values (API keys, tokens, private keys) are masked as labeled placeholders in variable, evaluate, and output results before they reach the agent (details; opt out with DEBUG_MCP_NO_REDACT=1)
• 🛡️ Path validation – Prevents crashes from non-existent files
• 📝 AI-aware line context – Intelligent breakpoint placement with code context
• ✅ Comprehensive test suite – unit, integration, and end-to-end coverage across every adapter (CI status)

🧠 Agent Skill

Tools tell an agent *what* it can do; a skill teaches it *how to debug well*. This repo ships an agent skill covering the session golden path, root-cause discipline (bisection over line-by-line stepping), attach/remote recipes, and per-language quirks:

# Claude Code (user-level)

cp -r skills/debugging ~/.claude/skills/mcp-debugger

Cross-agent directories (Copilot CLI and friends)

cp -r skills/debugging ~/.agents/skills/mcp-debugger

The server also serves condensed guidance in-band: MCP instructions on connect, plus a debugging-workflow prompt any MCP client can request. See skills/debugging/README.md for details.

🎬 See It In Action

• [Auto-debug failing CI tests](.github/actions/debug-failing-test/) – a composite GitHub Action that launches mcp-debugger + an agent on a test failure and posts the root-cause analysis
• [Sick pod walkthrough](examples/sick-pod/) – attach to a misbehaving Python service in Kubernetes via port-forward (tutorial)
• [Native sick pod](examples/sick-pod-cpp/) – same story for compiled code: ephemeral debug sidecar + attach-by-PID, no in-process agent required

🚀 Quick Start

Requirements: Node.js 22+ for the server. Each language you debug also needs its own toolchain installed (Python + debugpy, Ruby + the debug gem / rdbg, Node.js, Go + Delve, JDK 21+, .NET SDK, the Rust tool