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)

1. Claude detects something might be wrong (test failure, unexpected behavior, etc.)
2. Claude autonomously decides to debug instead of guessing
3. Breakpoints are set, program runs
4. Claude inspects locals, compares expected vs actual values
5. Claude identifies the discrepancy and fixes the bug

Fully autonomous — Claude invokes debugging tools on its own when investigating issues.

Installation

In Claude Code:

1. Use /plugin to open the plugin manager
2. Add the registry: bherbruck/mcp-debugger
3. Install the mcp-debugger plugin

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:

1. MCP Server (src/server.ts) — Routes tool calls from Claude Code to handlers
2. Session Manager (src/session/) — Manages debug session lifecycle and state machine
3. DAP Client (src/dap/) — Implements Debug Adapter Protocol, handles message parsing
4. Adapters (src/adapters/) — Language-specific debugger implementations (Python, JS/TS, Go, Rust)

See CLAUDE.md for detailed architecture notes.

License

MIT