mcp-debugger by debugmcp - MCP Server

mcp-debugger

MCP server for multi-language debugging – give your AI agents debugging superpowers 🚀

🎯 Overview

mcp-debugger is a Model Context Protocol (MCP) server that provides debugging tools as structured API calls. It enables AI agents to perform step-through debugging of multiple programming languages using the Debug Adapter Protocol (DAP).

🆕 Version 0.15.0: Dynamic adapter loading with monorepo packaging. Install adapters as optional dependencies. Start with Python and Mock; extend to any language.

🎬 Demo Video: See the debugger in action!

Recording in progress - This will show an AI agent discovering and fixing the variable swap bug in real-time

✨ Key Features

🌐 Multi-language support – Clean adapter pattern for any language
🐍 Python debugging via debugpy – Full DAP protocol support
🧪 Mock adapter for testing – Test without external dependencies
🔄 STDIO and SSE transport modes – Works with any MCP client
📊 1019 tests passing – battle-tested end-to-end
🐳 Docker and npm packages – Deploy anywhere
🤖 Built for AI agents – Structured JSON responses for easy parsing
🛡️ Path validation – Prevents crashes from non-existent files
📝 AI-aware line context – Intelligent breakpoint placement with code context

🚀 Quick Start

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", "--log-level", "debug", "--log-file", "C:/path/to/logs/debug-mcp-server.log"],
      "disabled": false,
      "autoApprove": ["create_debug_session", "set_breakpoint", "get_variables"]
    }
  }
}

For Claude Code CLI

For Claude Code users, we provide an automated installation script:

# Clone the repository
git clone https://github.com/yourusername/mcp-debugger.git
cd mcp-debugger

# Run the installation script
./scripts/install-claude-mcp.sh

# Verify the connection
/home/ubuntu/.claude/local/claude mcp list

Important: The stdio argument is required to prevent console output from corrupting the JSON-RPC protocol. See for detailed setup and for troubleshooting.

Using Docker

docker run -v $(pwd):/workspace debugmcp/mcp-debugger:latest

Using npm

npm install -g @debugmcp/mcp-debugger
mcp-debugger --help

Or use without installation via npx:

npx @debugmcp/mcp-debugger --help

📸 Screenshot: MCP Integration in Action

This screenshot will show real-time MCP protocol communication with tool calls and JSON responses flowing between the AI agent and debugger.

📚 How It Works

mcp-debugger exposes debugging operations as MCP tools that can be called with structured JSON parameters:

// Tool: create_debug_session
// Request:
{
  "language": "python",  // or "mock" for testing
  "name": "My Debug Session"
}
// Response:
{
  "success": true,
  "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
  "message": "Created python debug session: My Debug Session"
}

📸 Screenshot: Active Debugging Session

This screenshot will show the debugger paused at a breakpoint with the stack trace visible in the left panel, local variables in the right panel, and source code with line highlighting in the center.

🛠️ Available Tools

Tool	Description	Status
`create_debug_session`	Create a new debugging session	✅ Implemented
`list_debug_sessions`	List all active sessions	✅ Implemented
`set_breakpoint`	Set a breakpoint in a file	✅ Implemented
`start_debugging`	Start debugging a script	✅ Implemented
`get_stack_trace`	Get the current stack trace	✅ Implemented
`get_scopes`	Get variable scopes for a frame	✅ Implemented
`get_variables`	Get variables in a scope	✅ Implemented
`step_over`	Step over the current line	✅ Implemented
`step_into`	Step into a function	✅ Implemented
`step_out`	Step out of a function	✅ Implemented
`continue_execution`	Continue running	✅ Implemented
`close_debug_session`	Close a session	✅ Implemented
`pause_execution`	Pause running execution	❌ Not Implemented
`evaluate_expression`	Evaluate expressions	❌ Not Implemented
`get_source_context`	Get source code context	✅ Implemented

📸 Screenshot: Multi-Session Debugging

This screenshot will show the debugger managing multiple concurrent debug sessions, demonstrating how AI agents can debug different scripts simultaneously with isolated session management.

🏗️ Architecture: Dynamic Adapter Loading

Version 0.10.0 introduces a clean adapter pattern that separates language-agnostic core functionality from language-specific implementations:

┌─────────────┐     ┌──────────────┐     ┌─────────────────┐
│ MCP Client  │────▶│ SessionManager│────▶│ AdapterRegistry │
└─────────────┘     └──────────────┘     └─────────────────┘
                            │                      │
                            ▼                      ▼
                    ┌──────────────┐      ┌─────────────────┐
                    │ ProxyManager │◀─────│ Language Adapter│
                    └──────────────┘      └─────────────────┘
                                                   │
                                          ┌────────┴────────┐
                                          │                 │
                                    ┌─────▼──────┐   ┌─────▼──────┐
                                    │Python      │   │Mock        │
                                    │Adapter     │   │Adapter     │
                                    └────────────┘   └────────────┘

Adding Language Support

Want to add debugging support for your favorite language? Check out the !

💡 Example: Debugging Python Code

Here's a complete debugging session example:

# buggy_swap.py
def swap_variables(a, b):
    a = b  # Bug: loses original value of 'a'
    b = a  # Bug: 'b' gets the new value of 'a'
    return a, b

Step 1: Create a Debug Session

// Tool: create_debug_session
// Request:
{
  "language": "python",
  "name": "Swap Bug Investigation"
}
// Response:
{
  "success": true,
  "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
  "message": "Created python debug session: Swap Bug Investigation"
}

Step 2: Set Breakpoints

// Tool: set_breakpoint
// Request:
{
  "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
  "file": "buggy_swap.py",
  "line": 2
}
// Response:
{
  "success": true,
  "breakpointId": "28e06119-619e-43c0-b029-339cec2615df",
  "file": "C:\\path\\to\\buggy_swap.py",
  "line": 2,
  "verified": false,
  "message": "Breakpoint set at C:\\path\\to\\buggy_swap.py:2"
}

Step 3: Start Debugging

// Tool: start_debugging
// Request:
{
  "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
  "scriptPath": "buggy_swap.py"
}
// Response:
{
  "success": true,
  "state": "paused",
  "message": "Debugging started for buggy_swap.py. Current state: paused",
  "data": {
    "message": "Debugging started for buggy_swap.py. Current state: paused",
    "reason": "breakpoint"
  }
}

Step 4: Inspect Variables

First, get the scopes:

// Tool: get_scopes
// Request:
{
  "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
  "frameId": 3
}
// Response:
{
  "success": true,
  "scopes": [
    {
      "name": "Locals",
      "variablesReference": 5,
      "expensive": false,
      "presentationHint": "locals",
      "source": {}
    },
    {
      "name": "Globals", 
      "variablesReference": 6,
      "expensive": false,
      "source": {}
    }
  ]
}

Then get the local variables:

// Tool: get_variables
// Request:
{
  "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
  "scope": 5
}
// Response:
{
  "success": true,
  "variables": [
    {"name": "a", "value": "10", "type": "int", "variablesReference": 0, "expandable": false},
    {"name": "b", "value": "20", "type": "int", "variablesReference": 0, "expandable": false}
  ],
  "count": 2,
  "variablesReference": 5
}

📸 Screenshot: Variable Inspection Reveals the Bug

This screenshot will show the TUI visualizer after stepping over line 4, where both variables incorrectly show value 20, clearly demonstrating the variable swap bug. The left panel shows the execution state, the center shows the highlighted code, and the right panel displays the incorrect variable values.

📖 Documentation

📘 – Complete API documentation
🚦 – First-time setup
🏗️ – Multi-language design
🔧 – Add new languages
🔌 – Runtime discovery, lazy loading, caching
🧩 – Adapter, factory, loader, and registry contracts
🔄 – Upgrading to v0.15.0 (dynamic loading)
🐍 – Python-specific features
🤖 – Leverage AI-friendly features
🔧 – Common issues & solutions

🤝 Contributing

We welcome contributions! See for guidelines.

# Development setup
git clone https://github.com/debugmcp/mcp-debugger.git
cd mcp-debugger
npm install
npm run build
npm test

Running Container Tests Locally

We use Act to run GitHub Actions workflows locally:

# Build the Docker image first
docker build -t mcp-debugger:local .

# Run tests with Act (use WSL2 on Windows)
act -j build-and-test --matrix os:ubuntu-latest

See for detailed testing instructions.

📊 Project Status

✅ Production Ready: v0.15.0 with dynamic adapter loading
✅ 1019 tests passing end-to-end
✅ Clean architecture with adapter pattern
🚧 Coming Soon: Node.js, Go, and more language adapters
📈 Active Development: Regular updates and improvements

See for planned features.

📄 License

MIT License - see for details.

🙏 Acknowledgments

Built with:

Model Context Protocol by Anthropic
Debug Adapter Protocol by Microsoft
debugpy for Python debugging

Give your AI the power to debug like a developer – in any language! 🎯