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.
This tool executes Python code through the debugger. Use in trusted environments only.
Works best with uv
# 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
{
"mcpServers": {
"mcp-pdb": {
"command": "uv",
"args": [
"run",
"--with",
"mcp-pdb",
"mcp-pdb"
]
}
}
}
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 |
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 |
- 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
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
MIT License - See LICENSE file for details.