Polybugger

PyPI version License: MIT Tests Python 3.10+

Multi-language MCP debugger for AI agents. Debug Python, JavaScript/TypeScript, Go, and Rust with a single tool.

Install in Cursor Install in VS Code

Supported Languages

Demo

AI Debugging a Crashing Script

The AI uses polybugger to find a division-by-zero bug in a Python script:

Available Debug Tools

Session Continuity

Debug sessions persist across multiple interactions - no need to reconfigure breakpoints or restart:

Call Chain Visualization

See the complete call stack with source context at each frame:

Watch Expressions

Track variable values as they change through execution:

Why polybugger-mcp?

Key Features

• Multi-Language Debugging - Python, JavaScript/TypeScript, Go, Rust, and C/C++
• Container Debugging - Debug processes inside Docker, Podman, and Kubernetes
• Session Recovery - Persist debug state and resume after server restart
• Watch Expressions - Define expressions to track across every debug step
• Smart Data Inspection - Intelligent preview of DataFrames, NumPy arrays, dicts, and lists
• Call Hierarchy - Visualize the complete call chain with source context
• Full Interactive Debugging - Breakpoints, stepping, pause/continue
• Variable Inspection - View locals, globals, evaluate arbitrary expressions
• Rich TUI Output - ASCII box-drawn tables and diagrams for better visualization
• Pure Python - No Node.js required, just pip install
• Dual Interface - Use via MCP or standalone HTTP API
• Multi-Client Support - Cursor, VS Code, Claude Desktop, and more

Installation

Quick Install (no clone required)

Using uvx (recommended):

uvx polybugger-mcp

Using pipx:

pipx run polybugger-mcp

Using pip:

pip install polybugger-mcp
polybugger-mcp

MCP Client Configuration

Configure your MCP client to use one of these commands:

{
  "mcpServers": {
    "polybugger": {
      "command": "uvx",
      "args": ["polybugger-mcp"]
    }
  }
}

{
  "mcpServers": {
    "polybugger": {
      "command": "python",
      "args": ["-m", "polybugger_mcp.mcp_server"]
    }
  }
}

code --add-mcp '{"name":"polybugger","command":"uvx","args":["polybugger-mcp"]}'

claude mcp add polybugger -- uvx polybugger-mcp

{
  "mcpServers": {
    "polybugger": {
      "command": "uvx",
      "args": ["polybugger-mcp"]
    }
  }
}

{
  "mcp": {
    "polybugger": {
      "type": "local",
      "command": ["uvx", "polybugger-mcp"],
      "enabled": true
    }
  }
}

{
  "mcpServers": {
    "polybugger": {
      "command": "uvx",
      "args": ["polybugger-mcp"]
    }
  }
}

{
  "mcpServers": {
    "polybugger": {
      "command": "uvx",
      "args": ["polybugger-mcp"],
      "disabled": false
    }
  }
}

docker run -i --rm ghcr.io/wilfoa/polybugger-mcp

{
  "mcpServers": {
    "polybugger": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/wilfoa/polybugger-mcp"]
    }
  }
}

Available Tools (28 tools)

Session Management

Breakpoints

Execution Control

Inspection

Watch Expressions

Events & Output

Recovery

Container Debugging

Quick Start

1. Install the package:

   pip install polybugger-mcp
   

2. Configure your MCP client (see Installation above)

3. Start debugging: Ask your AI assistant:

   "Debug my script.py - set a breakpoint on line 15 and show me the variables when it stops"

Example Workflows

Basic Debugging

You: Debug tests/test_example.py - I want to see why the calculate function returns wrong results

AI: I'll create a debug session and set breakpoints in the calculate function.
    [Creates session, sets breakpoints, launches program]

    The program stopped at line 23. Here are the local variables:
    - x = 10
    - y = 5
    - result = 50  # This should be 15!

    I see the issue - you're using multiplication instead of addition on line 24.

Data Science Debugging

You: Debug my data pipeline and inspect the DataFrame at line 45

AI: [Sets breakpoint, launches program]

    The DataFrame `df` has 1000 rows x 5 columns (78.1 KB):

    ┌────────────┬────────────────┬────────┐
    │ Name       │ Type           │ Nulls  │
    ├────────────┼────────────────┼────────┤
    │ id         │ int64          │ -      │
    │ name       │ object         │ 5      │
    │ value      │ float64        │ 12     │
    └────────────┴────────────────┴────────┘

    I found 17 null values. The `value` column has NaN entries that may cause issues.

Call Hierarchy Visualization

You: Show me how we got to this breakpoint

AI: [Uses debug_get_call_chain with format="tui"]

    CALL CHAIN (4 frames)
    ════════════════════════════════════════════════════════════

    main (app.py:50)
    │ >> 50 │     result = process_order(order)
    │
    └─▶ process_order (orders.py:76)
        │ >> 76 │     pricing = apply_pricing(items, tier)
        │
        └─▶ apply_pricing (pricing.py:58)
            │ >> 58 │     discount = calculate_discount(subtotal)
            │
            └─▶ calculate_discount (pricing.py:23)  ◀── YOU ARE HERE
                │ >> 23 │     return base * rate

Container Debugging

You: Debug the Python process running in my Docker container "api-server"

AI: I'll list the Python processes in that container and attach the debugger.
    [Lists processes, finds PID 1234, injects debugpy, attaches]

    Successfully attached to process 1234 in container "api-server".
    The program is paused at the entry point. Here's the current state:
    - File: /app/server.py
    - Function: handle_request
    - Line: 45

    I can see the request object contains invalid JSON. The 'data' field is None.

Multi-Language Debugging

You: Debug my Go server - it's crashing on startup

AI: I'll create a Go debug session using Delve.
    [Creates session with language="go", sets breakpoints, launches]

    The program stopped at main.go:23. The config variable is nil
    because the environment variable CONFIG_PATH is not set.

Configuration

Environment variables (prefix with PYBUGGER_MCP_):

Development

# Clone and setup
git clone https://github.com/wilfoa/polybugger-mcp.git
cd polybugger-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Run tests
make test

# Run linter
make lint

# Run type checker
make typecheck

Recording Demo GIFs

Demo GIFs are created using VHS with OpenCode as the MCP client. To regenerate them:

# Install VHS
brew install charmbracelet/tap/vhs

# Configure OpenCode with polybugger MCP (in ~/.config/opencode/opencode.json)
# Add: "mcp": { "polybugger": { "type": "local", "command": ["uvx", "polybugger-mcp"], "enabled": true } }

# Generate the GIFs
vhs docs/tapes/debug_demo.tape              # Shows available debug tools
vhs docs/tapes/debug_full_demo.tape         # Full debugging workflow
vhs docs/tapes/session_continuity_demo.tape # Session persistence across interactions
vhs docs/tapes/call_chain_demo.tape         # Call stack visualization
vhs docs/tapes/watch_expressions_demo.tape  # Watch expressions feature
vhs docs/tapes/container_debug_demo.tape    # Container debugging

Architecture

                              ┌─────────────────┐
                              │  debugpy        │──▶ Python
                              ├─────────────────┤
AI Agent  ◀──▶  MCP Server  ◀─┤  Node Debug     │──▶ JavaScript/TypeScript
                              ├─────────────────┤
                              │  Delve          │──▶ Go
                              ├─────────────────┤
                              │  CodeLLDB       │──▶ Rust/C/C++
                              └─────────────────┘
                                     │
                              ┌──────┴──────┐
                              │  Container  │
                              │  Runtimes   │
                              ├─────────────┤
                              │ Docker      │
                              │ Podman      │
                              │ Kubernetes  │
                              └─────────────┘

The MCP server translates tool calls to Debug Adapter Protocol (DAP) messages for each language's debugger, enabling full debugging capabilities through natural language.

Requirements

• Python 3.10 or higher
• Works on macOS, Linux, and Windows

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.