MCP-PDB: Python Debugger Interface for Claude/LLMs

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

Common PDB Commands

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.