JesseObrien/mcp-debug-server

MCP Debug Server

⚠️ EXPERIMENTAL PROJECT - This is an experimental implementation. Use at your own risk.

An MCP (Model Context Protocol) server that provides Claude with direct debugging capabilities by leveraging existing Debug Adapter Protocol (DAP) implementations in major debuggers.

Installation

Global Installation

npm install -g mcp-debug-server

Run with npx (no installation required)

npx mcp-debug-server

Configuration

Add to your Claude Desktop configuration (claude_desktop_config.json):

For global installation:

{
  "mcpServers": {
    "debug": {
      "command": "mcp-debug-server",
      "args": []
    }
  }
}

For npx usage:

{
  "mcpServers": {
    "debug": {
      "command": "npx",
      "args": ["mcp-debug-server"]
    }
  }
}

Features

This MCP server provides Claude with 11 debugging tools that work with native debuggers:

• ✅ Go debugging: Complete implementation via dlv dap
• 🚧 Python/Node.js support: Requires plugin architecture (planned)
• Session management: Start/stop debug sessions with automatic cleanup
• Breakpoint control: Set conditional breakpoints in source files
• Execution control: Continue, step over, step into, step out
• Variable inspection: Examine local and global variables
• Expression evaluation: Evaluate expressions in debugger context
• Stack trace analysis: Get complete call stacks

Architecture

Claude → MCP Server → Direct TCP Connection → DAP Server (dlv/debugpy/node) → Debugger

The server acts as a bridge between Claude and existing Debug Adapter Protocol implementations, eliminating the need for custom debugger integration.

Supported Debuggers

✅ Currently Implemented

• Go: Uses dlv dap --listen=:0 - Complete debugging workflow

🚧 Planned (Plugin Architecture Required)

• Python: Uses python -m debugpy --listen localhost:0 --wait-for-client
• Node.js: Uses node --inspect=0.0.0.0:0

Note: Python and Node.js support require implementing a plugin architecture to handle language-specific DAP behaviors. See for details.

Available Tools

1. start_debug_session - Spawn DAP server and return session ID
2. set_breakpoint - Set breakpoint with optional condition
3. start_execution - Begin program execution after breakpoints are set
4. continue_execution - Continue program execution
5. step_over - Step over current line
6. step_into - Step into function call
7. step_out - Step out of current function
8. get_stack_trace - Get complete call stack
9. get_variables - Get variable values in current scope
10. evaluate_expression - Evaluate expressions in debugger context
11. stop_debug_session - Clean session shutdown

Usage Example

Once configured, Claude can autonomously debug programs:

User: "Debug my Go HTTP server - it's returning 500 errors"

Claude workflow:
1. Starts debug session with the Go program
2. Sets breakpoint in error handler
3. Continues execution while user triggers HTTP request
4. Examines variables when breakpoint hits
5. Evaluates expressions to understand the issue
6. Provides fix and stops debug session

Development Status

✅ Go Debugging Implementation Complete

• Complete MCP server with 11 debugging tools
• Full DAP protocol implementation with TCP communication
• Go debugger integration with dlv dap - all features working
• Comprehensive session management and error handling
• Integration tests demonstrating full debugging workflow
• Dynamic port assignment and process cleanup

🚧 Multi-Language Support

• Plugin architecture needed for Python/Node.js support
• Each language has unique DAP implementation quirks
• See for architecture details

Prerequisites

For Go Debugging (Currently Supported)

• Go: go install github.com/go-delve/delve/cmd/dlv@latest

For Future Language Support

• Python: pip install debugpy (requires plugin architecture)
• Node.js: Built-in (Node.js 8+) (requires plugin architecture)

License

MIT

Contributing

This project follows the Debug Adapter Protocol specification. All DAP messages must conform to the official JSON schema at: https://microsoft.github.io/debug-adapter-protocol/debugAdapterProtocol.json