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:
| mcp-debugger | microsoft/DebugMCP |
|---|
| Runs headless (CI, containers, k8s, cloud agents) | ✅ standalone Node process | ❌ requires a running VS Code |
| Transports | stdio + Streamable HTTP | Streamable HTTP (localhost) |
| Distribution | npx, npm, Docker image | VS Code Marketplace extension |
| Remote attach without an IDE | ✅ debugpy / rdbg / JDWP, incl. pods via port-forward | ❌ |
| Per-session process isolation | ✅ one proxy process per session | shares the VS Code instance |
Java hot-swap and Flutter hot reload (hot_reload) | ✅ | ❌ |
| Debuggee output as subscribable MCP resource | ✅ | ❌ |
| In-IDE debugging UX alongside the agent | ✅ read-only IDE mirror (expose_session) — the IDE joins the agent's live session | ✅ native |
| Logpoints without pausing (prod-safe value watching) | ✅ logMessage breakpoints | ✅ via VS Code |
Content/function-addressed breakpoints (statement:, function:, expectedContent) | ✅ agent-native addressing that survives edits | — |
| Secret redaction on by default | ✅ variable/evaluate/output masking + least-privilege mode | — |
| Kubernetes ephemeral debug sidecar (native attach-by-PID) | ✅ kubectl debug flow | ❌ |
| C/C++ | ✅ via CodeLLDB (launch + attach-by-PID) | ✅ via VS Code extensions |
| COBOL | ✅ via GnuCOBOL + CodeLLDB (launch + attach-by-PID, COBOL-shaped variables) | — |
| Dart/Flutter | ✅ via the SDK's own debug adapters (launch + attach by VM-service URI, or by deviceId for an app on an Android device; Dart programs and tests, Flutter apps and tests on desktop, web, Android emulators and devices, macOS and the iOS simulator; hot reload and hot restart) | — |
| PHP | ❌ | ✅ via VS Code extensions |
| Languages | Python, JS/TS, Ruby, Rust, Go, Java, .NET, C/C++, COBOL, Dart/Flutter | Python, JS/TS, Ruby, Rust, Go, Java, .NET, C/C++, PHP |
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.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
