🔍 debugger-mcp

The missing piece in AI agent tooling.

AI agents can read code, write code, search code, and run code. But they can't debug code. Until now.

mcp-debugger is an MCP server that gives AI agents real debugging superpowers — set breakpoints, inspect variables, step through code, evaluate expressions. Not simulated. Not "reading the code and guessing." Actually attaching a debugger and inspecting live runtime state.

Built on the Debug Adapter Protocol (DAP) — the same protocol VS Code uses — so it works with Python today, and C#, Java, Go, and every other language with a DAP adapter.

🧪 Born from a real moment: an AI agent was asked to set a breakpoint on a live .NET service. It couldn't. It tried installing debuggers, writing COM interop, attaching ClrMD — and still couldn't do what a developer does in 5 seconds with F9. This project exists so that never happens again.

---

⚡ See It In Action

🔧 debug_launch("app.py", breakpoints={"app.py": 22})
   → Launched PID 64844, breakpoint verified ✅

▶️  debug_continue()
   → STOPPED at breakpoint, reason: breakpoint

📚 debug_get_stack()
   → calculate_cost  @ app.py:22
     main            @ app.py:30
     <module>        @ app.py:36

📋 debug_get_locals()
   → cost = 0.0474            (float)
     usage (TokenUsage):
       .input_tokens  = 1547
       .output_tokens = 823
       .total_tokens  = 2370
       .model         = 'gpt-5.1'
       .cost_per_token = 2e-05

🔍 debug_evaluate("usage.total_tokens * usage.cost_per_token")
   → 0.047400000000000005

⏭️  debug_step_over()  → line 23
⏭️  debug_step_over()  → line 24
⏬  debug_step_into()  → stepped into get_discount()

📋 debug_get_locals()   → model_name = 'gpt-5.1'

🔌 debug_detach()       → done

That output is real. An AI agent set a breakpoint, hit it, read every local variable including nested object properties, evaluated a custom expression, stepped through code line by line, stepped into a function call, and inspected the inner scope. No mocks. No simulation.

---

🛠️ Tools

Tool	What it does
debug_launch	Launch a program under the debugger with optional breakpoints
debug_set_breakpoint	Set breakpoints by file and line number
debug_continue	Resume execution — blocks until next breakpoint hit
debug_get_stack	Get the full call stack with file and line info
debug_get_locals	Read all local variables — auto-expands objects one level
debug_evaluate	Evaluate any expression in the current scope
debug_step_over	Step over one line
debug_step_into	Step into a function call
debug_step_out	Step out of current function
debug_detach	Disconnect and clean up

---

🚀 Getting Started

Install

pip install debugpy   # Python debug adapter (required)
git clone https://github.com/YOUR_USERNAME/mcp-debugger.git

Run the demo

cd mcp-debugger
python examples/demo.py

Use in your code

from src import MCPDebugTools

dbg = MCPDebugTools()

# Launch with breakpoints
dbg.debug_launch("my_app.py", breakpoints={"my_app.py": [42, 67]})

# Wait for breakpoint hit
dbg.debug_continue()

# What's happening?
print(dbg.debug_get_locals())
print(dbg.debug_evaluate("len(users)"))

# Step through
dbg.debug_step_over()
dbg.debug_step_into()

# Done
dbg.debug_detach()

Use as MCP server (coming soon)

{
  "mcpServers": {
    "debugger": {
      "command": "python",
      "args": ["-m", "mcp_debugger"]
    }
  }
}

---

🏗️ How It Works

AI Agent (Copilot, Claude, Cursor, Windsurf, etc.)
    │
    ▼
MCP Server  ←  this project (thin layer, ~350 lines)
    │
    ▼
DAP Client  ←  Debug Adapter Protocol (same as VS Code)
    │
    ├──→ debugpy        (Python)     ✅ working
    ├──→ netcoredbg     (C# / .NET)  ✅ working
    ├──→ java-debug     (Java)       🔜 planned
    └──→ dlv dap        (Go)         🔜 planned

The key insight: VS Code already solved multi-language debugging with DAP. Every language has a debug adapter server. We just wrap DAP in MCP tools so AI agents can call them. One protocol, all languages.

---

🗺️ Roadmap

• DAP client implementation
• Python debugging via debugpy
• Core tools: launch, breakpoint, continue, locals, stack, evaluate, step
• MCP server wrapper (JSON-RPC over stdio)
• C# / .NET debugging via netcoredbg
• Java debugging via java-debug
• Go debugging via Delve
• Attach to already-running processes
• Conditional breakpoints
• Exception breakpoints (break on throw)
• Watch expressions
• Multi-session support

---

🤝 Contributing

This is an early-stage project and contributions are very welcome!

High-impact areas:

1. Adding language support — each language just needs a launcher module (~50 lines) that starts the right DAP server
2. MCP server packaging — wrapping the tools as a proper MCP server
3. Testing — edge cases, CI/CD, cross-platform
4. Attach support — debugging already-running processes

---

📄 License

MIT

---

If AI agents can read code, write code, search code, and run code — they should be able to debug code too.