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.25.0 — COBOL debugging lands (GnuCOBOL + CodeLLDB, with COBOL-shaped variables, PERFORM-aware stepping and paragraph breakpoints), and Rust and C/C++ work out of the box on every platform npm installs now that CodeLLDB ships as per-platform packages. Also new: mcp-debugger doctor, a Kubernetes debugging recipe, an HTTP transport locked to 127.0.0.1 with Host/Origin checks, launch responses that say how a run ended, exit codes for Go and Docker JavaScript, and a lighter startup. 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. Dart now; the Flutter runners are wired, measured on Windows desktop and the Android emulator in the spike, and ship in the next milestones (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 (legacy SSE transport is deprecated)
• 📦 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 – a composite GitHub Action that launches mcp-debugger + an agent on a test failure and posts the root-cause analysis
• Sick pod walkthrough – attach to a misbehaving Python service in Kubernetes via port-forward (tutorial)
• Native sick pod – 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 toolchain, a C/C++ compiler — g++/clang++, only needed for source-file launch — GnuCOBOL 3.1.2+ for COBOL source launch, or the Dart SDK — Flutter bundles one — for Dart/Flutter). Not sure what's installed? Run npx @debugmcp/mcp-debugger doctor for a per-adapter toolchain report.