uvx polybugger-mcp

pipx run polybugger-mcp

pip install polybugger-mcp
polybugger-mcp

{
  "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"]
    }
  }
}

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.

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.

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

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.

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.

# 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

# 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

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