MCP Debugger MCP server

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.

✨ 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. Both speak both protocol eras: the current 2026-07-28 revision (a probing client such as Claude Code's v2 runtime lands on it; sessionless on http) and 2025-11-25 and earlier (a client that opens with initialize)
• 📦 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.

CodeLLDB platform note (npx/npm installs): the CodeLLDB debug engine ships as per-platform optional dependencies (@debugmcp/codelldb-win32-x64, -darwin-x64, -darwin-arm64, -linux-x64, -linux-arm64) — npm installs exactly the one matching your platform, so Rust and C/C++ debugging work out of the box everywhere npm serves. If you install with --omit=optional, set CODELLDB_PATH to a CodeLLDB release binary instead, or use the Docker image.

For MCP Clients (Claude Desktop, etc.)

Add to your MCP settings configuration:

{
  "mcpServers": {
    "mcp-debugger": {
      "command": "node",
      "args": ["C:/path/to/mcp-debugger/dist/index.js", "stdio", "--log-level", "debug", "--log-file", "C:/path/to/logs/debug-mcp-server.log"],
      "disabled": false,
      "autoApprove": ["create_debug_session", "set_breakpoint", "get_variables"]
    }
  }
}

For Codex CLI, desktop, and IDE

Register the published stdio server with the Codex CLI:

codex mcp add mcp-debugger -- npx -y @debugmcp/mcp-debugger stdio
codex mcp list

Codex stores this entry in ~/.codex/config.toml. The ChatGPT desktop app, Codex CLI, and Codex IDE extension share that configuration when they run on the same Codex host. Restart the active desktop client or IDE extension (or start a new CLI session), then use /mcp to confirm that mcp-debugger is connected. See the official Codex MCP documentation for configuration and troubleshooting details.

Developing mcp-debugger itself? Use the restartable source dev proxy instead of the published package.

For Claude Code CLI

For Claude Code users, we provide an automated installation script:

Prerequisite: The Claude CLI must be installed and available on your PATH before running the installation script. See Claude Code documentation for installation instructions.

# Clone the repository
git clone https://github.com/debugmcp/mcp-debugger.git
cd mcp-debugger

# Run the installation script
./scripts/install-claude-mcp.sh

# Verify the connection (use 'claude mcp list' if claude is on your PATH)
claude mcp list

Important: The stdio argument is required to prevent console output from corrupting the JSON-RPC protocol. See CLAUDE.md for detailed setup and troubleshooting.

For the pi coding agent

pi 0.99 and later has built-in MCP support. The published @debugmcp/mcp-debugger package is also a pi package: one install adds the mcp-debugger agent skill and an extension that registers the server with pi's MCP support:

pi install npm:@debugmcp/mcp-debugger  # the mcp-debugger skill, and the server via pi's built-in MCP
pi list                                # shows the package

The extension runs the CLI that pi install put on disk, so the server matches the skill and starts without an npx download. It registers with deferred exposure: pi lists the debugger in its system prompt, and the model loads the tools it needs with tool_search, named mcp__mcp_debugger__<tool>. /mcp shows the server and changes its exposure for a session. A mcp-debugger entry in ~/.pi/agent/mcp.json replaces the registration, for example to debug a source build through the dev proxy.

To add only the server, without the skill: pi mcp add mcp-debugger -- npx -y @debugmcp/mcp-debugger stdio. pi older than 0.99 has no built-in MCP support; the extension then does nothing, so upgrade pi.

Using Docker

docker run -i --rm -v $(pwd):/workspace debugmcp/mcp-debugger:latest

The Docker image debugs Python, JavaScript, Java, Rust, C/C++, COBOL, and Dart natively (toolchains — GnuCOBOL and the Dart SDK included — plus a shared vendored CodeLLDB), plus the mock adapter. Flutter is host-only: the image carries no Flutter SDK. Ruby is attach-only in the image (the adapter ships without a Ruby runtime — attach to any rdbg --open process, local or remote). Only Go and .NET are disabled in the container — run those via npm/npx next to your local toolchain. Host-built Rust/C++ binaries debugged in the container get an auto-derived source map back to /workspace. list_supported_languages reports per-mode availability (modes.launch / modes.attach) with reasons. See Docker support.

Using npm

npm install -g @debugmcp/mcp-debugger
mcp-debugger --help

Or use without installation via npx:

npx @debugmcp/mcp-debugger --help

Over the network (Streamable HTTP)

stdio is the default and is what most clients want. When the server has to run somewhere else — a CI runner, a container, a Kubernetes pod — start it on a port instead:

mcp-debugger http --port 3001            # or: node dist/index.js http -p 3001

and point the client at it:

{
  "mcpServers": {
    "mcp-debugger": {
      "type": "http",
      "url": "http://127.0.0.1:3001/mcp"
    }
  }
}

The endpoint speaks both eras of the protocol: a client that probes with server/discover (Claude Code's v2 runtime does) gets the current 2026-07-28 revision, sessionless — every request stands alone, resource notifications flow over subscriptions/listen streams — and a client that opens with initialize gets the 2025 sessionful era, Mcp-Session-Id and all, exactly as before. GET /health counts the requests classified per era under requests (refused ones included).

One http process is one debugger: every MCP client of it sees the same debug sessions, and a session is addressable by whoever holds its id (the handle is the capability — run one process per agent if agents must not see each other's work). A debug session outlives the MCP session that created it, so a client that reconnects can list and resume or close what it left behind. A debug session ends by its own close, by its program ending, or with the server: nothing expires on a timer by default, so a quiet agent never loses a paused program. A server that is shared or long-lived, or that attaches to something that must not stay paused, can turn the idle policy on: with MCP_DEBUG_SESSION_IDLE_MS set, a session tree that no tool call has named for that long is closed (a launched program is ended, an attached one released), unless a client is attending the process — while any client holds a stream open (a 2025 session's SSE stream, a 2026-07-28 client's subscriptions/listen stream), nothing expires. A 2026 client that only calls tools is not attending: with the policy on, its sessions live by tool activity (and an in-flight wait_for_stop) alone, so choose a window longer than such a client's pauses. list_debug_sessions shows each session's idle time, so a forgotten one is easy to find and close. Abandoned MCP sessions themselves are reaped separately (MCP_HTTP_STREAM_LOST_SESSION_MS, MCP_HTTP_STALE_SESSION_MS). GET /health lists the MCP sessions, the debug sessions with their idle time, and whether anyone is attending.

The port defaults to 3001, and the server listens on 127.0.0.1 only. --bind 0.0.0.0 (or MCP_HTTP_BIND=0.0.0.0) listens on every interface — pair it with --allowed-host for the names other machines will use; --bind localhost means 127.0.0.1, and only IP addresses are accepted. GET /health on the same port answers a liveness check and reports the bound address and port under listening.

The server accepts only loopback Host headers by default — localhost, 127.0.0.1, [::1] — as DNS-rebinding protection for an unauthenticated endpoint that can spawn processes and attach to PIDs. A client on another machine reaches it through a port-forward or an SSH tunnel (ssh -L 3001:127.0.0.1:3001 user@server, then http://127.0.0.1:3001/mcp), or you bind an interface with --bind; any other Host gets a 403 that says so. To accept a service name directly — http://mcp-debugger:3001/mcp on a container network — start the server with --allowed-host mcp-debugger (repeatable) or MCP_HTTP_ALLOWED_HOSTS=mcp-debugger (comma-separated). That opt-in means another access control fronts the server; there is no wildcard. Browser clients are checked against the same list by their Origin, so a cross-site page cannot drive the debugger.

📚 How It Works

mcp-debugger exposes debugging operations as MCP tools that can be called with structured JSON parameters:

// Tool: create_debug_session
// Request:
{
  "language": "python",  // or "ruby", "javascript", "rust", "go", "java", "dotnet", "cpp", "cobol", "dart", or "mock" for testing
  "name": "My Debug Session"
}
// Response:
{
  "success": true,
  "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
  "message": "Created python debug session: My Debug Session"
}

🛠️ Available Tools

All 29 tools below are implemented — see the tool reference for parameters and response shapes.

Tool	Description	Status
create_debug_session	Create a new debugging session	✅ Implemented
list_debug_sessions	List all active sessions	✅ Implemented
list_supported_languages	Show available language adapters	✅ Implemented
set_breakpoint	Set a breakpoint in a file	✅ Implemented
list_breakpoints	List a session's breakpoints with verified state	✅ Implemented
remove_breakpoint	Remove a breakpoint by id or file+line	✅ Implemented
clear_breakpoints	Remove all breakpoints (optionally per file)	✅ Implemented
start_debugging	Start debugging a script — or a failing test in one call (testRunner: "pytest")	✅ Implemented
restart_debugging	Relaunch with the same config, breakpoints re-applied	✅ Implemented
attach_to_process	Attach debugger to a running process	✅ Implemented
detach_from_process	Detach debugger from a process	✅ Implemented
expose_session	Open a read-only DAP mirror endpoint so an IDE can attach and inspect	✅ Implemented
unexpose_session	Close the mirror endpoint and disconnect IDE clients	✅ Implemented
get_stack_trace	Get the current stack trace	✅ Implemented
list_threads	List all threads in the debug session	✅ Implemented
get_scopes	Get variable scopes for a frame	✅ Implemented
get_variables	Get variables in a scope	✅ Implemented
get_local_variables	Get local variables in current frame	✅ Implemented
step_over	Step over the current line	✅ Implemented
step_into	Step into a function	✅ Implemented
step_out	Step out of a function	✅ Implemented
continue_execution	Continue running	✅ Implemented
wait_for_stop	Block until the session next pauses or ends	✅ Implemented
pause_execution	Pause running execution	✅ Implemented
evaluate_expression	Evaluate expressions in debug context	✅ Implemented
get_source_context	Get source code context	✅ Implemented
get_output	Read captured debuggee output (stdout/stderr)	✅ Implemented
close_debug_session	Close a session	✅ Implemented
hot_reload	Apply changed code to the running program and keep its state — Flutter hot reload, Java class redefinition (redefine_classes is a deprecated alias)	✅ Implemented