What is Mcp Pdb

mcp-pdb is a Python debugging interface that integrates with Claude and other LLMs using the Model Context Protocol (MCP). It allows users to utilize Python’s debugger (pdb) for enhanced coding support.

Use cases

Use cases for mcp-pdb include debugging Python scripts in real-time, integrating debugging capabilities into AI-powered coding assistants, and enhancing educational tools for teaching programming.

How to use

To use mcp-pdb, install it via the command line with ‘claude mcp add mcp-pdb uv run --with mcp-pdb mcp-pdb’. You can then start debugging sessions, set breakpoints, and send commands to the debugger.

Key features

Key features include starting debugging sessions, setting and clearing breakpoints, examining variables, and listing breakpoints. It also supports common pdb commands for efficient debugging.

Where to use

mcp-pdb is suitable for software development, particularly in environments where Python code needs to be debugged interactively, such as during the development of applications using Claude and other LLMs.

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.