mcp-debugger is a headless MCP server that lets AI agents drive real debuggers — breakpoints, stepping, live variables — in CI runners, containers, Kubernetes pods, and cloud sandboxes. Nine languages, 28 tools. No IDE anywhere in the loop.
$ npx @debugmcp/mcp-debugger stdio
Then mcp-debugger doctor prints a per-language table of what's installed, what's missing, and how to fix it.
where IDEs can't go
An IDE debugger needs an IDE, a screen, and a human at the keyboard. Agents work where none of those exist — and that's exactly where the interesting failures live.
On test failure, the agent sets real breakpoints in the failing path, inspects live values, and posts the root cause as a PR comment.
- uses: debugmcp/mcp-debugger/.github/actions/debug-failing-test@mainThe debug-failing-test action →
Attach to a misbehaving pod through a port-forward, inspect the state your logs never captured, detach. Compiled process with no debug agent? Send the debugger to the pod as an ephemeral sidecar and attach by PID.
$ kubectl debug pod/checkout --image=debugmcp/mcp-debugger …Just-in-time diagnostics tutorial →
Claude Code, Copilot, Cursor, and headless harnesses connect over stdio or HTTP. A debug session becomes structured tool calls an agent can reason about.
$ claude mcp add-json mcp-debugger …Client setup →
languages
Every adapter drives the language's own production debugger through the Debug Adapter Protocol — the same engines your IDE would use, without the IDE.
| Language | Engine | Launch | Attach | Remote attach | Notable |
|---|---|---|---|---|---|
| Python | debugpy | ✓ | ✓ | ✓ | logpoints, function breakpoints |
| JavaScript / TypeScript | js-debug | ✓ | ✓ | ✓ | VS Code's engine, V8 inspector attach, function breakpoints via CDP |
| Ruby | rdbg | ✓ | ✓ | ✓ | attach into containers & pods |
| Rust | CodeLLDB | ✓ | — | — | Cargo-aware launch, logpoints |
| Go | Delve | ✓ | — | — | native DAP, logpoints |
| Java | JDI bridge | ✓ | ✓ | ✓ | JDWP attach, class hot-swap |
| .NET / C# | netcoredbg | ✓ | ✓ | — | PID attach, portable PDB handling |
| C / C++ | CodeLLDB | ✓ | ✓ | — | attach by PID, k8s ephemeral sidecar, auto-compile, core dumps |
| COBOL | GnuCOBOL + CodeLLDB | ✓ | ✓ | — | COBOL-shaped variables, PERFORM-aware stepping, paragraph breakpoints, attach by PID |
Plus a mock adapter for testing agent integrations without any toolchain installed. Logpoints — log a value and keep running, never pausing — work on Python, JavaScript, Go, Rust, C/C++ and COBOL. Function breakpoints work on every adapter except Ruby. Breakpoints can be addressed by statement content (statement:), by symbol (function:), or by line with an expectedContent assertion — anchors that survive the agent's own edits and re-resolve across a relaunch. Launch sessions pause on uncaught exceptions by default (Ruby excepted — rdbg has no uncaught-only filter). npm installs pull only your platform's CodeLLDB build, so Rust and C/C++ work out of the box on Windows, macOS and Linux.
choosing a 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 projects make different structural trade-offs:
| mcp-debugger | microsoft/DebugMCP | |
|---|---|---|
| Runs headless (CI, containers, k8s, cloud) | ✓ standalone process | requires running VS Code |
| Transports | stdio + Streamable HTTP | HTTP (localhost) |
| Distribution | npx, npm, Docker, PyPI launcher | VS Code Marketplace |
| Remote attach without an IDE | ✓ debugpy / rdbg / JDWP / V8 inspector | — |
| Per-session process isolation | ✓ | shares the VS Code instance |
| Content/function-addressed breakpoints | ✓ statement: / function: — survive the agent's edits | — |
| Debuggee output as a subscribable MCP resource | ✓ | — |
| Logpoints without pausing | ✓ prod-safe value watching | ✓ via VS Code |
| Kubernetes ephemeral debug sidecar | ✓ kubectl debug + attach by PID | — |
| Java hot-swap | ✓ | — |
| In-IDE debugging UX beside the agent | ✓ read-only IDE mirror — your IDE joins the agent's live session | ✓ native |
| Secret redaction on by default | ✓ + least-privilege variable mode | — |
| C/C++ | ✓ CodeLLDB, launch + attach-by-PID | ✓ via VS Code extensions |
| PHP | — | ✓ via VS Code extensions |
If your agent runs in a terminal, a pipeline, or a cloud sandbox — or needs to reach a process on another machine — you want mcp-debugger.
agent skill
mcp-debugger ships an agent skill: when to reach for the debugger, the session golden path, root-cause bisection discipline, and the per-language quirks we learned so your agent doesn't have to. The server also serves condensed guidance in-band via MCP instructions and a debugging-workflow prompt.
From a clone of the repo, copy it into your agent's skills directory — ~/.claude/skills/ for Claude Code, ~/.agents/skills/ or ~/.copilot/skills/ for other harnesses. Any other agent can read SKILL.md directly as a rules file. The skill also ships inside the npm package: pi install npm:@debugmcp/mcp-debugger registers the server and the skill in one step, and any harness that reads a skills directory can point at node_modules/@debugmcp/mcp-debugger/skills/debugging. The skill →
$ cp -r skills/debugging ~/.claude/skills/mcp-debugger
who stands behind this
mcp-debugger is stewarded by Sycamore LLC and led by John Franklin. AI agents write most of the code; a human maintainer makes every merge, release, and security decision. The project is MIT-licensed — the grant doesn't depend on the steward.
gh attestation verify or npm audit signatures