Skip to content
Back to search

mcp-debugger

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/debugmcp/mcp-debugger with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/debugmcp/mcp-debugger'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/debugmcp--mcp-debugger/badge.svg)](/listings/debugmcp--mcp-debugger)

HTML

<a href="/listings/debugmcp--mcp-debugger"><img src="/api/listings/debugmcp--mcp-debugger/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

> **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 — or GnuCOBOL 3.1.2+ for COBOL source launch). 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](https://github.com/vadimcn/codelldb/releases) 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](https://developers.openai.com/codex/mcp) for configuration and troubleshooting details.

Developing mcp-debugger itself? Use the restartable [source dev proxy](tools/dev-proxy/README.md#codex-cli-desktop-and-ide) 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](https://claude.ai/code) 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](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](tools/dev-proxy/README.md).

To add only the server, without the skill: `pi mcp add mcp-debugger -- npx -y @debugmcp/mcp-debugger stdio`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 608 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # mcp-debugger
  2. <div align="center">
  3. <img src="assets/logo.png" alt="MCP Debugger Logo - A stylized circuit board with debug breakpoints" width="400" height="400">
  4. </div>
  5. **A headless, agentic debugger over MCP — let your AI agents debug running programs in ten languages.**
  6. [![CI](https://github.com/debugmcp/mcp-debugger/actions/workflows/ci.yml/badge.svg)](https://github.com/debugmcp/mcp-debugger/actions/workflows/ci.yml)
  7. [![codecov](https://codecov.io/gh/debugmcp/mcp-debugger/branch/main/graph/badge.svg)](https://codecov.io/gh/debugmcp/mcp-debugger)
  8. [![npm version](https://img.shields.io/npm/v/@debugmcp/mcp-debugger.svg)](https://www.npmjs.com/package/@debugmcp/mcp-debugger)
  9. [![Docker Pulls](https://img.shields.io/docker/pulls/debugmcp/mcp-debugger.svg)](https://hub.docker.com/r/debugmcp/mcp-debugger)
  10. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
  11. [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/debugmcp/mcp-debugger/badge)](https://scorecard.dev/viewer/?uri=github.com/debugmcp/mcp-debugger)
  12. [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/13543/badge)](https://www.bestpractices.dev/projects/13543)
  13. ## 🎯 Overview
  14. 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).
  15. **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.
  16. ### When to use mcp-debugger vs an IDE-bound debug server
  17. Microsoft's [DebugMCP](https://github.com/microsoft/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:
  18. | | mcp-debugger | microsoft/DebugMCP |
  19. |---|---|---|
  20. | Runs headless (CI, containers, k8s, cloud agents) | ✅ standalone Node process | ❌ requires a running VS Code |
  21. | Transports | stdio + Streamable HTTP | Streamable HTTP (localhost) |
  22. | Distribution | npx, npm, Docker image | VS Code Marketplace extension |
  23. | Remote attach without an IDE | ✅ debugpy / rdbg / JDWP, incl. pods via port-forward | ❌ |
  24. | Per-session process isolation | ✅ one proxy process per session | shares the VS Code instance |
  25. | Java hot-swap and Flutter hot reload (`hot_reload`) | ✅ | ❌ |
  26. | Debuggee output as subscribable MCP resource | ✅ | ❌ |
  27. | In-IDE debugging UX alongside the agent | ✅ read-only IDE mirror ([`expose_session`](docs/tool-reference.md#expose_session)) — the IDE joins the *agent's* live session | ✅ native |
  28. | Logpoints without pausing (prod-safe value watching) | ✅ [`logMessage` breakpoints](docs/tool-reference.md#set_breakpoint) | ✅ via VS Code |
  29. | Content/function-addressed breakpoints (`statement:`, `function:`, `expectedContent`) | ✅ agent-native addressing that survives edits | — |
  30. | Secret redaction on by default | ✅ variable/evaluate/output masking + least-privilege mode | — |
  31. | Kubernetes ephemeral debug sidecar (native attach-by-PID) | ✅ [`kubectl debug` flow](docs/kubernetes.md) | ❌ |
  32. | C/C++ | ✅ via CodeLLDB (launch + attach-by-PID) | ✅ via VS Code extensions |
  33. | COBOL | ✅ via GnuCOBOL + CodeLLDB (launch + attach-by-PID, COBOL-shaped variables) | — |
  34. | 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) | — |
  35. | PHP | ❌ | ✅ via VS Code extensions |
  36. | 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 |
  37. 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.
  38. > 🆕 **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](./CHANGELOG.md) for the full release history.
  39. ## ✨ Key Features
  40. - 🌐 **Multi-language support** – Clean adapter pattern for any language
  41. - 🐍 **Python debugging via debugpy** – Full DAP protocol support
  42. - 💎 **Ruby debugging via rdbg** – Launch and attach workflows, including remote attach to containers and Kubernetes pods
  43. - 🟨 **JavaScript (Node.js) debugging via js-debug** – VSCode's proven debugger
  44. - 🦀 **Rust debugging via CodeLLDB** – Debug Rust & Cargo projects (Linux/macOS; Windows needs the GNU toolchain — see [Rust on Windows](docs/rust-debugging-windows.md))
  45. - 🐹 **Go debugging via Delve** – Full DAP support for Go programs
  46. - ☕ **Java debugging via JDI bridge** – Launch and attach modes with JDK 21+
  47. - 🔷 **.NET/C# debugging via netcoredbg** – Debug .NET applications with full DAP support
  48. - ⚙️ **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
  49. - 🧮 **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](docs/cobol/README.md))
  50. - 🐦 **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](docs/dart/README.md))
  51. - 🧪 **Mock adapter for testing** – Test without external dependencies
  52. - 🛰️ **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
  53. - 🎯 **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
  54. - 🪵 **Logpoints** – `set_breakpoint` with `logMessage: "x={x}"` streams interpolated values into `get_output` without pausing — prod-safe value watching on hot paths
  55. - 🧰 **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
  56. - 📡 **Buffered program output** – `get_output` returns debuggee stdout/stderr with a cursor, and each session exposes its transcript as a subscribable MCP resource
  57. - 💥 **Crash-state debugging by default** – Launch sessions pause on uncaught exceptions with stack and locals live (`breakOnExceptions`; exception class/message surfaced via `lastStop`)
  58. - 🪞 **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
  59. - ☸️ **Kubernetes debugging** – port-forward attach for interpreted runtimes, `kubectl debug --target` + attach-by-PID for native processes ([recipe](docs/kubernetes.md), [turnkey manifests](examples/kubernetes/))
  60. - 🔌 **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`)
  61. - 📦 **Zero-runtime dependencies** – Self-contained bundles via esbuild + tsup
  62. - ⚡ **npx ready** – Run directly with `npx @debugmcp/mcp-debugger` - no installation needed
  63. - 🐳 **Docker and npm packages** – Deploy anywhere
  64. - 🤖 **Built for AI agents** – Structured JSON responses for easy parsing
  65. - 🔒 **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](./docs/tool-reference.md#secret-redaction); opt out with `DEBUG_MCP_NO_REDACT=1`)
  66. - 🛡️ **Path validation** – Prevents crashes from non-existent files
  67. - 📝 **AI-aware line context** – Intelligent breakpoint placement with code context
  68. - ✅ **Comprehensive test suite** – unit, integration, and end-to-end coverage across every adapter ([CI status](https://github.com/debugmcp/mcp-debugger/actions/workflows/ci.yml))
  69. ## 🧠 Agent Skill
  70. Tools tell an agent *what* it can do; a skill teaches it *how to debug well*. This repo ships an [agent skill](skills/debugging/) covering the session golden path, root-cause discipline (bisection over line-by-line stepping), attach/remote recipes, and per-language quirks:
  71. ```bash
  72. # Claude Code (user-level)
  73. cp -r skills/debugging ~/.claude/skills/mcp-debugger
  74. # Cross-agent directories (Copilot CLI and friends)
  75. cp -r skills/debugging ~/.agents/skills/mcp-debugger
  76. ```
  77. 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](skills/debugging/README.md) for details.
  78. ## 🎬 See It In Action
  79. - **[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
  80. - **[Sick pod walkthrough](examples/sick-pod/)** – attach to a misbehaving Python service in Kubernetes via port-forward ([tutorial](docs/jit-diagnostics/README.md))
  81. - **[Native sick pod](examples/sick-pod-cpp/)** – same story for compiled code: ephemeral debug sidecar + attach-by-PID, no in-process agent required
  82. ## 🚀 Quick Start
  83. > **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.
  84. >
  85. > **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](https://github.com/vadimcn/codelldb/releases) binary instead, or use the Docker image.
  86. ### For MCP Clients (Claude Desktop, etc.)
  87. Add to your MCP settings configuration:
  88. ```json
  89. {
  90. "mcpServers": {
  91. "mcp-debugger": {
  92. "command": "node",
  93. "args": ["C:/path/to/mcp-debugger/dist/index.js", "stdio", "--log-level", "debug", "--log-file", "C:/path/to/logs/debug-mcp-server.log"],
  94. "disabled": false,
  95. "autoApprove": ["create_debug_session", "set_breakpoint", "get_variables"]
  96. }
  97. }
  98. }
  99. ```
  100. ### For Codex CLI, desktop, and IDE
  101. Register the published stdio server with the Codex CLI:
  102. ```bash
  103. codex mcp add mcp-debugger -- npx -y @debugmcp/mcp-debugger stdio
  104. codex mcp list
  105. ```
  106. Codex stores this entry in `~/.codex/config.toml`. The ChatGPT desktop app, Codex CLI,
  107. and Codex IDE extension share that configuration when they run on the same Codex host.
  108. Restart the active desktop client or IDE extension (or start a new CLI session), then use
  109. `/mcp` to confirm that `mcp-debugger` is connected. See the official
  110. [Codex MCP documentation](https://developers.openai.com/codex/mcp) for configuration and
  111. troubleshooting details.
  112. Developing mcp-debugger itself? Use the restartable [source dev proxy](tools/dev-proxy/README.md#codex-cli-desktop-and-ide)
  113. instead of the published package.
  114. ### For Claude Code CLI
  115. For Claude Code users, we provide an automated installation script:
  116. > **Prerequisite**: The Claude CLI must be installed and available on your PATH before running the installation script. See [Claude Code documentation](https://claude.ai/code) for installation instructions.
  117. ```bash
  118. # Clone the repository
  119. git clone https://github.com/debugmcp/mcp-debugger.git
  120. cd mcp-debugger
  121. # Run the installation script
  122. ./scripts/install-claude-mcp.sh
  123. # Verify the connection (use 'claude mcp list' if claude is on your PATH)
  124. claude mcp list
  125. ```
  126. **Important**: The `stdio` argument is required to prevent console output from corrupting the JSON-RPC protocol. See [CLAUDE.md](CLAUDE.md) for detailed setup and troubleshooting.
  127. ### For the pi coding agent
  128. pi 0.99 and later has built-in MCP support. The published `@debugmcp/mcp-debugger` package is
  129. also a pi package: one install adds the `mcp-debugger` agent skill and an extension that registers
  130. the server with pi's MCP support:
  131. ```bash
  132. pi install npm:@debugmcp/mcp-debugger # the mcp-debugger skill, and the server via pi's built-in MCP
  133. pi list # shows the package
  134. ```
  135. The extension runs the CLI that `pi install` put on disk, so the server matches the skill and
  136. starts without an `npx` download. It registers with `deferred` exposure: pi lists the debugger in
  137. its system prompt, and the model loads the tools it needs with `tool_search`, named
  138. `mcp__mcp_debugger__<tool>`. `/mcp` shows the server and changes its exposure for a session. A
  139. `mcp-debugger` entry in `~/.pi/agent/mcp.json` replaces the registration, for example to debug a
  140. source build through the [dev proxy](tools/dev-proxy/README.md).
  141. To add only the server, without the skill: `pi mcp add mcp-debugger -- npx -y @debugmcp/mcp-debugger stdio`.
  142. pi older than 0.99 has no built-in MCP support; the extension then does nothing, so upgrade pi.
  143. ### Using Docker
  144. ```bash
  145. docker run -i --rm -v $(pwd):/workspace debugmcp/mcp-debugger:latest
  146. ```
  147. > 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](./docs/docker-support.md).
  148. ### Using npm
  149. ```bash
  150. npm install -g @debugmcp/mcp-debugger
  151. mcp-debugger --help
  152. ```
  153. Or use without installation via npx:
  154. ```bash
  155. npx @debugmcp/mcp-debugger --help
  156. ```
  157. ### Over the network (Streamable HTTP)
  158. `stdio` is the default and is what most clients want. When the server has to run somewhere else
  159. — a CI runner, a container, a Kubernetes pod — start it on a port instead:
  160. ```bash
  161. mcp-debugger http --port 3001 # or: node dist/index.js http -p 3001
  162. ```
  163. and point the client at it:
  164. ```json
  165. {
  166. "mcpServers": {
  167. "mcp-debugger": {
  168. "type": "http",
  169. "url": "http://127.0.0.1:3001/mcp"
  170. }
  171. }
  172. }
  173. ```
  174. The endpoint speaks both eras of the protocol: a client that probes with `server/discover` (Claude
  175. Code's v2 runtime does) gets the current 2026-07-28 revision, sessionless — every request stands
  176. alone, resource notifications flow over `subscriptions/listen` streams — and a client that opens
  177. with `initialize` gets the 2025 sessionful era, `Mcp-Session-Id` and all, exactly as before.
  178. `GET /health` counts the requests classified per era under `requests` (refused ones included).
  179. One `http` process is one debugger: every MCP client of it sees the same debug sessions, and a
  180. session is addressable by whoever holds its id (the handle is the capability — run one process
  181. per agent if agents must not see each other's work). A debug session outlives the MCP session
  182. that created it, so a client that reconnects can list and resume or close what it left behind.
  183. A debug session ends by its own close, by its program ending, or with the server: nothing expires
  184. on a timer by default, so a quiet agent never loses a paused program. A server that is shared or
  185. long-lived, or that attaches to something that must not stay paused, can turn the idle policy on:
  186. with `MCP_DEBUG_SESSION_IDLE_MS` set, a session tree that no tool call has named for that long is
  187. closed (a launched program is ended, an attached one released), unless a client is attending the
  188. process — while any client holds a stream open (a 2025 session's SSE stream, a 2026-07-28
  189. client's `subscriptions/listen` stream), nothing expires. A 2026 client that only calls tools is
  190. not attending: with the policy on, its sessions live by tool activity alone — a call in flight
  191. holds its session, and the window starts over when it answers — so choose a window longer than
  192. such a client's pauses between calls.
  193. `list_debug_sessions` shows each session's idle time, so a forgotten one is easy to find and
  194. close. Abandoned MCP
  195. sessions themselves are reaped separately (`MCP_HTTP_STREAM_LOST_SESSION_MS`,
  196. `MCP_HTTP_STALE_SESSION_MS`). `GET /health` lists the MCP sessions, the debug sessions with
  197. their idle time, and whether anyone is attending.
  198. The port defaults to 3001, and the server listens on `127.0.0.1` only. `--bind 0.0.0.0` (or
  199. `MCP_HTTP_BIND=0.0.0.0`) listens on every interface — pair it with `--allowed-host` for the names other
  200. machines will use; `--bind localhost` means `127.0.0.1`, and only IP addresses are accepted. `GET /health`
  201. on the same port answers a liveness check and reports the bound address and port under `listening`.
  202. The server accepts only loopback `Host` headers by default — `localhost`, `127.0.0.1`, `[::1]` —
  203. as DNS-rebinding protection for an unauthenticated endpoint that can spawn processes and attach to
  204. PIDs. A client on another machine reaches it through a port-forward or an SSH tunnel
  205. (`ssh -L 3001:127.0.0.1:3001 user@server`, then `http://127.0.0.1:3001/mcp`), or you bind an
  206. 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
  207. container network — start the server with `--allowed-host mcp-debugger` (repeatable) or
  208. `MCP_HTTP_ALLOWED_HOSTS=mcp-debugger` (comma-separated). That opt-in means another access control
  209. fronts the server; there is no wildcard. Browser clients are checked against the same list by
  210. their `Origin`, so a cross-site page cannot drive the debugger.
  211. ## 📚 How It Works
  212. mcp-debugger exposes debugging operations as MCP tools that can be called with structured JSON parameters:
  213. ```json
  214. // Tool: create_debug_session
  215. // Request:
  216. {
  217. "language": "python", // or "ruby", "javascript", "rust", "go", "java", "dotnet", "cpp", "cobol", "dart", or "mock" for testing
  218. "name": "My Debug Session"
  219. }
  220. // Response:
  221. {
  222. "success": true,
  223. "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
  224. "message": "Created python debug session: My Debug Session"
  225. }
  226. ```
  227. ## 🛠️ Available Tools
  228. All **29 tools** below are implemented — see the [tool reference](docs/tool-reference.md) for parameters and response shapes.
  229. | Tool | Description | Status |
  230. |------|-------------|--------|
  231. | `create_debug_session` | Create a new debugging session | ✅ Implemented |
  232. | `list_debug_sessions` | List all active sessions | ✅ Implemented |
  233. | `list_supported_languages` | Show available language adapters | ✅ Implemented |
  234. | `set_breakpoint` | Set a breakpoint in a file | ✅ Implemented |
  235. | `list_breakpoints` | List a session's breakpoints with verified state | ✅ Implemented |
  236. | `remove_breakpoint` | Remove a breakpoint by id or file+line | ✅ Implemented |
  237. | `clear_breakpoints` | Remove all breakpoints (optionally per file) | ✅ Implemented |
  238. | `start_debugging` | Start debugging a script — or a failing test in one call (`testRunner: "pytest"`) | ✅ Implemented |
  239. | `restart_debugging` | Relaunch with the same config, breakpoints re-applied | ✅ Implemented |
  240. | `attach_to_process` | Attach debugger to a running process | ✅ Implemented |
  241. | `detach_from_process` | Detach debugger from a process | ✅ Implemented |
  242. | `expose_session` | Open a read-only DAP mirror endpoint so an IDE can attach and inspect | ✅ Implemented |
  243. | `unexpose_session` | Close the mirror endpoint and disconnect IDE clients | ✅ Implemented |
  244. | `get_stack_trace` | Get the current stack trace | ✅ Implemented |
  245. | `list_threads` | List all threads in the debug session | ✅ Implemented |
  246. | `get_scopes` | Get variable scopes for a frame | ✅ Implemented |
  247. | `get_variables` | Get variables in a scope | ✅ Implemented |
  248. | `get_local_variables` | Get local variables in current frame | ✅ Implemented |
  249. | `step_over` | Step over the current line | ✅ Implemented |
  250. | `step_into` | Step into a function | ✅ Implemented |
  251. | `step_out` | Step out of a function | ✅ Implemented |
  252. | `continue_execution` | Continue running | ✅ Implemented |
  253. | `wait_for_stop` | Block until the session next pauses or ends | ✅ Implemented |
  254. | `pause_execution` | Pause running execution | ✅ Implemented |
  255. | `evaluate_expression` | Evaluate expressions in debug context | ✅ Implemented |
  256. | `get_source_context` | Get source code context | ✅ Implemented |
  257. | `get_output` | Read captured debuggee output (stdout/stderr) | ✅ Implemented |
  258. | `close_debug_session` | Close a session | ✅ Implemented |
  259. | `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 |
  260. ## 🏗️ Architecture: Dynamic Adapter Loading
  261. Version 0.10.0 introduces a clean adapter pattern that separates language-agnostic core functionality from language-specific implementations:
  262. ```
  263. ┌─────────────┐ ┌────────────────┐ ┌──────────────┐ ┌─────────────────┐
  264. │ MCP Client │────▶│ DebugMcpServer │────▶│SessionManager│────▶│ AdapterRegistry │
  265. └─────────────┘ └────────────────┘ └──────────────┘ └─────────────────┘
  266. │ │
  267. ▼ ▼
  268. ┌──────────────┐ ┌─────────────────┐
  269. │ ProxyManager │◀─────│ Language Adapter│
  270. └──────────────┘ └─────────────────┘
  271. │
  272. ┌───────────┬───────────┬───────────┼───────────┬───────────┬───────────┬───────────┬───────────┬───────────┬───────────┐
  273. │ │ │ │ │ │ │ │ │ │ │
  274. ┌─────▼────┐┌─────▼────┐┌─────▼────┐┌─────▼────┐┌─────▼────┐┌─────▼────┐┌─────▼────┐┌─────▼────┐┌─────▼────┐┌─────▼────┐┌─────▼────┐
  275. │Python ││Ruby ││JavaScript││Rust ││Go ││Java ││.NET ││C/C++ ││COBOL ││Dart ││Mock │
  276. │Adapter ││Adapter ││Adapter ││Adapter ││Adapter ││Adapter ││Adapter ││Adapter ││Adapter ││Adapter ││Adapter │
  277. └──────────┘└──────────┘└──────────┘└──────────┘└──────────┘└──────────┘└──────────┘└──────────┘└──────────┘└──────────┘└──────────┘
  278. ```
  279. ### Adding Language Support
  280. Want to add debugging support for your favorite language? Check out the [Adapter Development Guide](./docs/architecture/adapter-development-guide.md)!
  281. ## 💡 Example: Debugging Python Code
  282. Here's a complete debugging session example:
  283. ```python
  284. # buggy_swap.py
  285. def swap_variables(a, b):
  286. a = b # Bug: loses original value of 'a'
  287. b = a # Bug: 'b' gets the new value of 'a'
  288. return a, b
  289. ```
  290. ### Step 1: Create a Debug Session
  291. ```json
  292. // Tool: create_debug_session
  293. // Request:
  294. {
  295. "language": "python",
  296. "name": "Swap Bug Investigation"
  297. }
  298. // Response:
  299. {
  300. "success": true,
  301. "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
  302. "message": "Created python debug session: Swap Bug Investigation"
  303. }
  304. ```
  305. ### Step 2: Set Breakpoints
  306. ```json
  307. // Tool: set_breakpoint
  308. // Request:
  309. {
  310. "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
  311. "file": "C:\\path\\to\\buggy_swap.py",
  312. "line": 2
  313. }
  314. // Response:
  315. {
  316. "success": true,
  317. "breakpointId": "28e06119-619e-43c0-b029-339cec2615df",
  318. "file": "C:\\path\\to\\buggy_swap.py",
  319. "line": 2,
  320. "verified": false,
  321. "message": "Breakpoint set at C:\\path\\to\\buggy_swap.py:2"
  322. }
  323. ```
  324. ### Step 3: Start Debugging
  325. ```json
  326. // Tool: start_debugging
  327. // Request:
  328. {
  329. "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
  330. "scriptPath": "C:\\path\\to\\buggy_swap.py"
  331. }
  332. // Response:
  333. {
  334. "success": true,
  335. "state": "paused",
  336. "message": "Debugging started for C:\\path\\to\\buggy_swap.py. Current state: paused",
  337. "data": {
  338. "message": "Debugging started for C:\\path\\to\\buggy_swap.py. Current state: paused",
  339. "reason": "breakpoint"
  340. }
  341. }
  342. ```
  343. ### Step 4: Inspect Variables
  344. First, get the scopes:
  345. ```json
  346. // Tool: get_scopes
  347. // Request:
  348. {
  349. "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
  350. "frameId": 3
  351. }
  352. // Response:
  353. {
  354. "success": true,
  355. "scopes": [
  356. {
  357. "name": "Locals",
  358. "variablesReference": 5,
  359. "expensive": false,
  360. "presentationHint": "locals",
  361. "source": {}
  362. },
  363. {
  364. "name": "Globals",
  365. "variablesReference": 6,
  366. "expensive": false,
  367. "source": {}
  368. }
  369. ]
  370. }
  371. ```
  372. Then get the local variables:
  373. ```json
  374. // Tool: get_variables
  375. // Request:
  376. {
  377. "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
  378. "scope": 5
  379. }
  380. // Response:
  381. {
  382. "success": true,
  383. "variables": [
  384. {"name": "a", "value": "10", "type": "int", "variablesReference": 0, "expandable": false},
  385. {"name": "b", "value": "20", "type": "int", "variablesReference": 0, "expandable": false}
  386. ],
  387. "count": 2,
  388. "variablesReference": 5
  389. }
  390. ```
  391. ## 📖 Documentation
  392. - 🗺️ [Roadmap](./ROADMAP.md) – Path to 1.0: stability criteria, near-term themes, non-goals
  393. - 📘 [Tool Reference](./docs/tool-reference.md) – Complete API documentation
  394. - 🚦 [Getting Started Guide](./docs/getting-started.md) – First-time setup
  395. - 🏗️ [Architecture Overview](./docs/architecture/README.md) – Multi-language design
  396. - 🔧 [Adapter Development](./docs/architecture/adapter-development-guide.md) – Add new languages
  397. - 🔌 [Dynamic Loading Architecture](./docs/architecture/dynamic-loading-architecture.md) – Runtime discovery, lazy loading, caching
  398. - 🧩 [Adapter API Reference](./docs/architecture/adapter-api-reference.md) – Adapter, factory, loader, and registry contracts
  399. - 🌳 [Session Tree Design](./docs/architecture/session-tree.md) – A debuggee's child processes as debug sessions (issue #1005; shipped for Python, #1081, and JavaScript, #1082)
  400. - 🔄 [CHANGELOG](./CHANGELOG.md) – Release history and upgrade notes
  401. - 🐍 [Python Debugging Guide](./docs/python/README.md) – Python-specific features
  402. - 💎 [Ruby Debugging Guide](./docs/ruby/README.md) – Ruby debugging with `rdbg`, including remote attach
  403. - 🔬 [Case Study: the initialize response that never came](./docs/case-studies/rdbg-initialize-response-stall.md) – mcp-debugger debugging itself to root-cause a Ruby launch stall
  404. - 🔬 [Case Study: attaching the debugger to itself](./docs/case-studies/self-attach-fork-release-and-the-500ms-ack-window.md) – live-patching a running mcp-debugger through its own `evaluate_expression` to catch a race strace couldn't see
  405. - 🔬 [Case Study: the pause that always succeeded](./docs/case-studies/js-attach-pause-and-the-smart-stepper.md) – reading js-debug's own CDP trace to catch its smart-stepper eating user pauses on idle servers
  406. - 🔬 [Case Study: the trace that couldn't name its socket](./docs/case-studies/trace-that-couldnt-name-its-socket.md) – measure-fix-measure on the diagnostics themselves: one scripted attach run, before and after, as the acceptance test
  407. - 🟨 [JavaScript Debugging Guide](./docs/javascript/README.md) – JavaScript/TypeScript features
  408. - 🐹 [Go Debugging Guide](./docs/go/README.md) – Go debugging with Delve
  409. - ☕ [Java Debugging Guide](./docs/java/README.md) – Java debugging with JDI bridge
  410. - 🔷 [.NET Debugging Guide](./docs/dotnet/README.md) – .NET/C# debugging with netcoredbg
  411. - ⚙️ [C/C++ Debugging Guide](./docs/cpp/README.md) – CodeLLDB launch, auto-compile, attach-by-PID, core dumps, remote stubs
  412. - 🧮 [COBOL Debugging Guide](./docs/cobol/README.md) – GnuCOBOL + CodeLLDB: auto-compile, COBOL-shaped variables, runtime-error stops, the mainframe migration recipe
  413. - 🐦 [Dart/Flutter Debugging Guide](./docs/dart/README.md) – the SDK's own debug adapters: runner selection, `dart test`/`flutter test`, attach by VM-service URI, Flutter devices
  414. - 🦀 [Rust Debugging Guide](./docs/rust-debugging.md) – CodeLLDB setup ([Windows specifics](docs/rust-debugging-windows.md))
  415. - 🐳 [Docker Support](./docs/docker-support.md) – Container languages, attach modes, host-binary source mapping
  416. - ☸️ [Kubernetes Debugging](./docs/kubernetes.md) – Turnkey attach recipes: registry-free manifests, per-language presets, ephemeral debug sidecar
  417. - 🚑 [JIT Diagnostics Tutorial](./docs/jit-diagnostics/README.md) – Debug live services in Kubernetes, incl. the ephemeral-sidecar flow for compiled code
  418. - 🤖 [Agent Debugging Guide](./docs/agent-debugging-guide.md) – Correct tool usage patterns for AI agents
  419. - ⚠️ [Known Issues](./docs/KNOWN_ISSUES.md) – Current caveats and workarounds
  420. - 🩺 [Diagnostics](./docs/diagnostics.md) – `mcp-debugger doctor`, per-language prerequisites, failure signatures, env-var reference
  421. - 🔧 [Troubleshooting](./docs/troubleshooting.md) – Common issues & solutions
  422. ## 🤝 Contributing
  423. We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
  424. ```bash
  425. # Development setup
  426. git clone https://github.com/debugmcp/mcp-debugger.git
  427. cd mcp-debugger
  428. # Install dependencies and vendor debug adapters
  429. pnpm install
  430. # Vendored debug engines (Microsoft's js-debug; CodeLLDB, shared by Rust, C/C++ and COBOL)
  431. # are downloaded automatically and verified against committed SHA-256 digest pins
  432. # Build the project
  433. pnpm build
  434. # Run tests
  435. pnpm test
  436. # Check adapter vendoring status
  437. pnpm vendor:status
  438. # Force re-vendor all adapters (if needed)
  439. pnpm vendor:force
  440. ```
  441. ### Debug Adapter Vendoring
  442. The project automatically vendors debug adapters during `pnpm install`:
  443. - **JavaScript**: Downloads Microsoft's js-debug from GitHub releases
  444. - **Rust, C/C++ & COBOL**: Download a single shared copy of CodeLLDB for the current platform (`packages/codelldb-common`)
  445. - **Integrity**: Every download is verified against the pinned SHA-256 digests in the packages' `vendor-manifest.json`; mismatches fail the build
  446. - **CI Environment**: Set `SKIP_ADAPTER_VENDOR=true` to skip vendoring
  447. To manually manage adapters:
  448. ```bash
  449. # Check current vendoring status
  450. pnpm vendor:status
  451. # Re-vendor all adapters
  452. pnpm vendor
  453. # Clean and re-vendor (force)
  454. pnpm vendor:force
  455. # Clean vendor directories only
  456. pnpm clean:vendor
  457. ```
  458. ### Running Container Tests Locally
  459. We use [Act](https://github.com/nektos/act) to run GitHub Actions workflows locally:
  460. ```bash
  461. # Build the Docker image first
  462. docker build -t mcp-debugger:local .
  463. # Run tests with Act (use WSL2 on Windows)
  464. act -j build-and-test --matrix os:ubuntu-latest
  465. ```
  466. See [tests/README.md](./tests/README.md) for detailed testing instructions.
  467. ## 📊 Project Status
  468. - ✅ **Production Ready**: ten language adapters, 29 tools, and polished multi-language distribution
  469. - ✅ **Clean architecture** with a dynamic adapter pattern
  470. - ✅ **Python · Ruby · JavaScript/TypeScript · Go · Java · .NET/C#**: Full step-through debugging
  471. - 🦀 **Rust**: Full support on Linux/macOS/Windows (Windows requires the GNU toolchain; MSVC is not supported by CodeLLDB)
  472. - ⚙️ **C/C++**: Full step-through debugging via CodeLLDB (launch + attach-by-PID; on Windows prefer MinGW/DWARF — MSVC PDB fidelity is partial)
  473. - 🧮 **COBOL**: Step-through debugging via GnuCOBOL + CodeLLDB (launch + attach-by-PID; verified with GnuCOBOL 3.1.2/3.2 on Linux and Windows/MSYS2; PERFORM-aware stepping, paragraph breakpoints and `{WS-NAME}` logpoints)
  474. - 🐦 **Dart/Flutter**: Step-through debugging through the SDK's own debug adapters (`dart debug_adapter`, `flutter debug-adapter`; launch + attach by VM-service URI, or by `deviceId` on Android). Dart programs and `dart test`; Flutter apps and tests on desktop, web (Chrome/Edge), Android emulators and devices, macOS and the iOS simulator; hot reload and hot restart
  475. - 🟢 **Runtime**: Node.js 22+
  476. - 📈 **Active Development**: Regular updates and improvements — see the [Roadmap](./ROADMAP.md) for the path to 1.0
  477. ## 🏛️ Who Maintains This
  478. mcp-debugger is stewarded by **Sycamore LLC** and led by John Franklin ([@debugmcpdev](https://github.com/debugmcpdev)). The project uses an agent-first development model with human accountability: AI agents write most of the code; a human maintainer makes every merge, release, and security decision. See [MAINTAINERS.md](./MAINTAINERS.md), [GOVERNANCE.md](./GOVERNANCE.md), and [SUPPORT.md](./SUPPORT.md) (including commercial support).
  479. Supply-chain posture: pinned CI actions, OIDC trusted publishing, sigstore provenance on every npm package, SBOMs attached to releases, and an [OpenSSF Scorecard](https://scorecard.dev/viewer/?uri=github.com/debugmcp/mcp-debugger) score we actively maintain — details in [SUPPLY-CHAIN-SECURITY.md](./SUPPLY-CHAIN-SECURITY.md). Report vulnerabilities via [SECURITY.md](./SECURITY.md).
  480. ## 📄 License
  481. MIT License - see [LICENSE](./LICENSE) for details.
  482. ## 👥 Contributors
  483. - [@Poyraxx](https://github.com/Poyraxx) — Ruby adapter (rdbg)
  484. - [@swinyx](https://github.com/swinyx) — Go adapter (Delve)
  485. - [@roofpig95008](https://github.com/roofpig95008) — Java adapter (JDI bridge)
  486. ## 🙏 Acknowledgments
  487. Built with:
  488. - [Model Context Protocol](https://github.com/anthropics/model-context-protocol) by Anthropic
  489. - [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/) by Microsoft
  490. - [debugpy](https://github.com/microsoft/debugpy) for Python debugging
  491. - [debug](https://github.com/ruby/debug) for Ruby debugging
  492. ---
  493. **Give your AI agents a real debugger — in any language.**

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.