MCP Debugger
A Claude Code plugin that enables fully autonomous debugging — coding agents pause programs, step through execution, inspect locals, and compare expected vs actual values using real debuggers. No human intervention. No log statements.
This is a game changer for AI-assisted development. Claude autonomously investigates bugs by debugging itself, finding discrepancies between expected and actual runtime state. It works today.
Why This Exists
Traditional AI debugging means:
- Stop execution
- Edit code to add debug logs
- Adjust log levels
- Rerun the program
- Parse log spam
- Repeat
This wastes tokens, time, and iteration cycles.
MCP Debugger eliminates all of that.
No debug logs. No log levels. No reruns. No code edits. Claude pauses your running program, inspects the actual state, and tells you what's wrong — in one shot.
Result: Faster debugging, fewer tokens spent on log spam, and no polluted git diffs from print statements.
What Makes This Different
- ✓ Fully Autonomous: Claude decides when to debug, sets breakpoints, and investigates without human prompting
- ✓ Real DAP Backends: Uses production debuggers (debugpy, vscode-js-debug, Delve, CodeLLDB), not mocks or interpreters
- ✓ Expanded Locals: Inspects full object trees, compares expected vs actual values
- ✓ Multi-Language: Same autonomous debugging across Python, JavaScript/TypeScript, Go, and Rust
This isn't "AI explains stack traces" or "human-directed debugging" — it's autonomous runtime investigation.
Claude debugs itself. No human intervention required.
Language Support
Fully functional with real debugger backends:
- Python — debugpy
- JavaScript / TypeScript — vscode-js-debug
- Go — Delve
- Rust — CodeLLDB
Debug adapters auto-install on first use.
How It Works
Claude Code → MCP Protocol → mcp-debugger → DAP → Runtime Debugger
↓
Your Program (paused)
- Claude detects something might be wrong (test failure, unexpected behavior, etc.)
- Claude autonomously decides to debug instead of guessing
- Breakpoints are set, program runs
- Claude inspects locals, compares expected vs actual values
- Claude identifies the discrepancy and fixes the bug
Fully autonomous — Claude invokes debugging tools on its own when investigating issues.
Installation
In Claude Code:
- Use
/pluginto open the plugin manager - Add the registry:
bherbruck/mcp-debugger - Install the
mcp-debuggerplugin
That's it. Claude autonomously uses it when investigating issues — no commands needed.
Optional: Add to your CLAUDE.md to encourage autonomous debugging over print statements:
## Debugging
Use the mcp-debugger plugin for debugging instead of adding print/log statements.
Set breakpoints and inspect variables using real debuggers.
Requirements: Language runtimes for what you want to debug (Python 3.7+, Node.js 18+, Go 1.18+, Rust). Debug adapters install automatically on first use.
Concrete Example
Scenario: A test fails. Expected return value, got None instead.
Claude (autonomously): Test failure detected. Instead of guessing or adding logs, I'll debug this to see what's actually happening at runtime.
[Claude creates debug session, sets breakpoint at process_orders(), runs code]
Paused at line 47 in process_orders()
Stack frame:
process_orders() → validate_items() → calculate_total()
Expanded locals at breakpoint:
orders = [
Order(id=1, items=[...], total=150.00, status='pending'),
Order(id=2, items=[], total=0.00, status='pending'), ← suspicious
Order(id=3, items=[...], total=200.00, status='pending')
]
valid_orders = []
[Claude steps into validate_items(), inspects]
Found it: Order #2 has an empty items list. The function returns None
when items is empty instead of raising an exception or returning an
empty result.
The bug is in line 52 — it returns early without a value when
len(order.items) == 0.
[Claude fixes the bug to return an empty result instead of None]
Claude found and fixed this autonomously. No log statements added. No human debugging. Just runtime inspection, expected vs actual comparison, and a fix.
Who This Is For
- Autonomous coding agents that need to debug themselves without human intervention
- Developers who want agents to investigate and fix bugs independently
- Anyone building with AI agents who's tired of log-based debugging cycles
This is agent-first debugging. Claude investigates, debugs, and fixes autonomously.
Scope & Safety
Intended for: Local development and debugging environments Not intended for: Production runtime debugging (yet) Agent capabilities: Inspect state, set breakpoints, evaluate expressions Agent limitations: Cannot modify code through the debugger
MCP Debugger gives agents read-only runtime inspection. It's designed for dev environments where pausing execution is safe.
Known limitations: Rust multithreaded debugging behaves like a regular VS Code debugger — cross-thread symbol resolution can be limited. This is a CodeLLDB/DAP limitation, not specific to MCP Debugger.
Available Tools
Claude has access to these debugging capabilities (invoked automatically):
Session Management: create_debug_session, start_debugging, terminate_session, list_sessions
Breakpoints: set_breakpoint, remove_breakpoint, list_breakpoints
Execution Control: continue, pause, step_in, step_over, step_out
Inspection: get_stack_trace, get_variables, expand_variable, evaluate_expression, get_source_context
You don't call these directly — Claude chooses when to use them.
Development & Architecture
Build: npm install && npm run build
Test: npm test
Watch: npm run dev
Architecture layers:
- MCP Server (
src/server.ts) — Routes tool calls from Claude Code to handlers - Session Manager (
src/session/) — Manages debug session lifecycle and state machine - DAP Client (
src/dap/) — Implements Debug Adapter Protocol, handles message parsing - Adapters (
src/adapters/) — Language-specific debugger implementations (Python, JS/TS, Go, Rust)
See CLAUDE.md for detailed architecture notes.
License
MIT