Skip to content

samefarrar/mcp-pdb

Repository files navigation

MCP-PDB: Python Debugger Interface for Claude/LLMs

Python License

MCP-PDB provides tools for using Python's debugger (pdb) with Claude and other LLMs through the Model Context Protocol (MCP). This was inspired by debug-gym by Microsoft, which showed gains in various coding benchmarks by providing a coding agent access to a python debugger.

⚠️ Security Warning

This tool executes Python code through the debugger. Use in trusted environments only.

Installation

Works best with uv

Claude Code

# Install the MCP server
claude mcp add mcp-pdb -- uv run --with mcp-pdb mcp-pdb

# Alternative: Install with specific Python version
claude mcp add mcp-pdb -- uv run --python 3.13 --with mcp-pdb mcp-pdb

# Note: The -- separator is required for Claude Code CLI

Windsurf

{
  "mcpServers": {
    "mcp-pdb": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-pdb",
        "mcp-pdb"
      ]
    }
  }
}

Available Tools

Tool Description
start_debug(file_path, use_pytest, args) Start a debugging session for a Python file
send_pdb_command(command) Send a command to the running PDB instance
set_breakpoint(file_path, line_number) Set a breakpoint at a specific line
clear_breakpoint(file_path, line_number) Clear a breakpoint at a specific line
list_breakpoints() List all current breakpoints
restart_debug() Restart the current debugging session
examine_variable(variable_name) Get detailed information about a variable
get_debug_status() Show the current state of the debugging session
end_debug() End the current debugging session

Common PDB Commands

Command Description
n Next line (step over)
s Step into function
c Continue execution
r Return from current function
p variable Print variable value
pp variable Pretty print variable
b file:line Set breakpoint
cl num Clear breakpoint
l List source code
q Quit debugging

Features

  • Project-aware debugging with automatic virtual environment detection
  • Support for both direct Python debugging and pytest-based debugging
  • Automatic breakpoint tracking and restoration between sessions
  • Works with UV package manager
  • Variable inspection with type information and attribute listing

Troubleshooting

Claude Code Installation Issues

If you encounter an error like:

MCP server "mcp-pdb" Connection failed: spawn /Users/xxx/.local/bin/uv run --python 3.13 --with mcp-pdb mcp-pdb ENOENT

Make sure to include the -- separator when using claude mcp add:

# ✅ Correct
claude mcp add mcp-pdb -- uv run --with mcp-pdb mcp-pdb

# ❌ Incorrect (missing --)
claude mcp add mcp-pdb uv run --with mcp-pdb mcp-pdb

To verify your installation:

# Check if mcp-pdb is listed
claude mcp list | grep mcp-pdb

# Check server status in Claude Code
# Type /mcp in Claude Code to see connection status

License

MIT License - See LICENSE file for details.

About

No description, website, or topics provided.

Resources

Stars

Watchers

Forks

Packages

No packages published

Languages