Skip to main content
Glama

Debug-MCP: Python Debugging via Model Context Protocol

A Python debugging tool that exposes breakpoint-based debugging capabilities through a clean API and CLI, designed for integration with AI assistants and development tools.

English | 日本語

Features

  • Advanced Debugging via DAP: Production-ready debugging using Microsoft's debugpy

    • Breakpoint Debugging: Set breakpoints and inspect local variables at runtime

    • Step Execution: True step-in, step-over, step-out operations

    • No Corruption: Isolated process execution prevents sys.modules issues

    • Environment-aware: Automatically uses target project's Python interpreter

  • Session Management: Isolated debug sessions with timeout protection

  • Dual Interface:

    • CLI: Interactive debugging with beautiful table output

    • MCP Server: Official MCP SDK-based integration for AI assistants

  • Safe Execution: Sandboxed subprocess execution with configurable limits

  • Type Safety: Pydantic v2 schemas for request/response validation

  • Async Support: Built on MCP SDK with full async/await support

  • Comprehensive Testing: 254 tests (119 unit + 122 integration + 13 exploration) covering DAP workflows, session management, and edge cases

  • Legacy Compatibility: Optional bdb mode for backward compatibility

Related MCP server: mcp-debugpy

Quick Start

Installation

# Clone repository
git clone https://github.com/your-org/Debug-MCP.git
cd Debug-MCP

# Create virtual environment
uv venv

# Install with CLI support
uv pip install -e ".[cli]"

VS Code Copilot Integration

To use this tool with GitHub Copilot in VS Code, set up the MCP server configuration.

See VS Code Setup Guide for detailed instructions.

Quick Setup (Using from Debug-MCP repository):

  1. Create MCP config directory (macOS/Linux):

    mkdir -p ~/Library/Application\ Support/Code/User/globalStorage/github.copilot-chat
  2. Edit mcp.json file:

    {
      "mcpServers": {
        "python-debug": {
          "command": "uv",
          "args": ["run", "mcp-debug-server", "--workspace", "${workspaceFolder}"],
          "env": {"PYTHONUNBUFFERED": "1"}
        }
      }
    }
  3. Restart VS Code

Using from Another Repository:

When using this tool from a different repository, specify the Debug-MCP installation path:

{
  "mcpServers": {
    "python-debug": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/Debug-MCP",
        "run",
        "mcp-debug-server",
        "--workspace",
        "${workspaceFolder}"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

Replace /absolute/path/to/Debug-MCP with the actual path to your Debug-MCP installation.

Using Copilot Chat:

@workspace Set a breakpoint at line 42 in src/main.py and 
show me the local variables at that point.

See mcp-config-example.json for a complete configuration example.

# Start a debug session
SESSION_ID=$(uv run mcp-debug start-session src/app.py | jq -r .sessionId)

# Run to breakpoint and inspect locals  
uv run mcp-debug run-to-breakpoint $SESSION_ID src/app.py 42 --format table

# Continue to next breakpoint
uv run mcp-debug continue $SESSION_ID src/app.py 100 --format table

# Check session state
uv run mcp-debug state $SESSION_ID --format table

# End session
uv run mcp-debug end $SESSION_ID

See Quickstart Guide for more CLI examples.

API Usage (Python Integration)

from pathlib import Path
from mcp_debug_tool.sessions import SessionManager
from mcp_debug_tool.schemas import StartSessionRequest, BreakpointRequest

# Initialize
workspace = Path.cwd()
manager = SessionManager(workspace)

# Create session
req = StartSessionRequest(entry="src/main.py", args=["--verbose"])
session = manager.create_session(req)

# Run to breakpoint
bp_req = BreakpointRequest(file="src/main.py", line=15)
result = manager.run_to_breakpoint(session.sessionId, bp_req)

if result.hit:
    print(f"Paused at {result.frameInfo.file}:{result.frameInfo.line}")
    print(f"Locals: {result.locals}")

# Continue execution
continue_result = manager.continue_execution(
    session.sessionId, 
    BreakpointRequest(file="src/main.py", line=42)
)

# Cleanup
manager.end_session(session.sessionId)

Safety & Constraints

Execution Limits

  • Timeout: 20 seconds per breakpoint operation (configurable)

  • Output Capture: 10MB maximum per session

  • Variable Depth: Max 2 levels of nesting in local variable inspection

  • Collection Size: Max 50 items shown in lists/dicts

  • String Length: Max 256 characters before truncation

Security

  • Path Validation: Only project-relative paths allowed (no .. traversal)

  • Subprocess Isolation: Debuggee runs in isolated subprocess

  • Working Directory: Locked to workspace root

  • No Network: Debuggee has no special network access (app code may still use network)

⚠️ Important: The debugger executes user code with minimal restrictions. Only debug trusted code.

Architecture

Current Implementation (v2 - DAP-based)

Debug-MCP now uses DAP (Debug Adapter Protocol) via debugpy for production debugging:

┌─────────────────────────────────────────────────┐
│ MCP Server (server.py)                          │
│ - Official MCP SDK (async)                      │
│ - Tool registration & routing                   │
└────────────────┬────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────┐
│ Session Manager (sessions.py)                   │
│ - Lifecycle management                          │
│ - DAP/bdb mode selection                        │
└────────────────┬────────────────────────────────┘
                 │
                 ▼ (DAP mode - default)
┌─────────────────────────────────────────────────┐
│ DAPSyncWrapper (dap_wrapper.py)                 │
│ - Synchronous DAP interface                     │
│ - Event queue management                        │
│ - Timeout handling                              │
└────────────────┬────────────────────────────────┘
                 │ DAP Protocol (JSON-RPC)
                 ▼
┌─────────────────────────────────────────────────┐
│ debugpy Server (separate process)               │
│ - Microsoft's official DAP implementation       │
│ - Handles breakpoints, stepping, variables      │
│ - Manages target script execution               │
└────────────────┬────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────┐
│ Target Python Script                            │
│ - Runs in isolated process                      │
│ - Full access to target dependencies            │
│ - No sys.modules corruption                     │
└─────────────────────────────────────────────────┘

Why DAP (debugpy)?

  • ✅ No sys.modules corruption - Runs in separate process

  • ✅ True step execution - Maintains execution state across steps

  • ✅ Automatic environment handling - Uses target Python interpreter

  • ✅ Industry standard - Microsoft's battle-tested implementation

  • ✅ Rich features - Step in/over/out, conditional breakpoints, watch expressions

  • ✅ Future-proof - Easy to extend with advanced debugging features

Communication Flow:

  1. MCP Client (VS Code Copilot) → MCP Server (tool call)

  2. Server → SessionManager (sync method via async wrapper)

  3. SessionManager → DAPSyncWrapper (manages DAP session)

  4. DAPSyncWrapper ↔ debugpy Server (DAP protocol over socket)

  5. debugpy captures locals → DAPSyncWrapper → SessionManager → Server → Client

Legacy bdb Mode

The bdb-based implementation is still available for compatibility (useDap=false):

SessionManager → runner_main.py (subprocess) → DebugController (bdb)

However, DAP is now the default and recommended for all use cases. The bdb mode has known issues:

  • sys.modules corruption with multiple runs

  • No true step execution (replay-based)

  • Complex PYTHONPATH management

File Organization (2025-11-03)

Active Files (Production):

  • ✅ server.py - MCP SDK server

  • ✅ sessions.py - Session lifecycle management

  • ✅ dap_wrapper.py - DAP synchronous wrapper (PRIMARY)

  • ✅ dap_client.py - Low-level DAP protocol client (PRIMARY)

  • ✅ schemas.py - Pydantic models

  • ✅ utils.py - Variable repr helpers and path utilities

Legacy Files (Compatibility):

  • ⚠️ debugger.py - bdb-based engine (legacy, use useDap=false)

  • ⚠️ runner_main.py - bdb subprocess runner (legacy)

Removed Files:

  • runner.py - Old multiprocessing approach (removed 2025-10-30)

Development

Setup

See docs/development.md for detailed setup instructions.

Quick commands:

# Run all tests (254 tests: 119 unit + 122 integration + 13 exploration)
uv run pytest

# Run only unit tests
uv run pytest tests/unit/

# Run only integration tests
uv run pytest tests/integration/

# Run tests with coverage
uv run pytest --cov=src/mcp_debug_tool --cov-report=html

# Lint
uv run ruff check .

# Format  
uv run ruff format .

# Auto-fix lint issues
uv run ruff check --fix .

Project Structure

Debug-MCP/
├── src/
│   ├── mcp_debug_tool/      # Core debugging engine
│   │   ├── server.py        # MCP SDK-based server (v2.0+)
│   │   ├── sessions.py      # Session management (DAP/bdb mode selection)
│   │   ├── dap_wrapper.py   # DAP synchronous wrapper (PRIMARY)
│   │   ├── dap_client.py    # DAP protocol client (PRIMARY)
│   │   ├── debugger.py      # bdb-based debugger (LEGACY, use useDap=false)
│   │   ├── runner_main.py   # bdb subprocess runner (LEGACY)
│   │   ├── schemas.py       # Pydantic models
│   │   └── utils.py         # Variable repr helpers
│   └── cli/
│       └── main.py          # Typer CLI
├── tests/
│   ├── unit/                # Unit tests (debugger, schemas, DAP, sessions)
│   └── integration/         # Integration tests (DAP workflows, bdb compat)
├── specs/
│   └── 001-python-debug-tool/  # Specification documents
└── docs/                    # Additional documentation
    ├── dap-phase*-*.md      # DAP integration documentation
    └── roadmap.md           # Future enhancements

Documentation

Current Status

v2.0 Released! DAP Integration Complete 🎉

  • ✅ Phase 1: Foundation (Complete - 6/6 tests passing)

  • ✅ Phase 2: Core Logic (Complete - 28/28 tests passing)

  • ✅ Phase 3: Session Lifecycle (Complete - 29/29 tests passing)

  • ✅ Phase 4: Breakpoint Operations (Complete - 41/41 tests passing)

  • ✅ Phase 5: Error Visibility (Complete - 71/71 tests passing)

  • ✅ Phase 6: MCP SDK Migration (Complete - SDK-based server with async support)

  • ✅ Phase 7: DAP Integration (Complete - Production-ready debugpy integration)

What's New in v2.0:

  • DAP (debugpy) is now the default - No more sys.modules corruption!

  • True step execution - Step in, step over, step out all working

  • Automatic environment handling - Uses target project's Python interpreter

  • Industry-standard protocol - Microsoft's battle-tested implementation

  • Enhanced reliability - Isolated process execution prevents crashes

  • Backward compatible - Legacy bdb mode still available with useDap=false

Migration from v1.x:

  • Existing code works as-is (DAP is opt-in by default)

  • To explicitly use bdb: StartSessionRequest(entry="...", useDap=False)

  • Recommended: Let it default to DAP for best results

Limitations (v2)

  • Script entry only: No module (python -m) or pytest target support (planned for v2.1)

  • Single-threaded: No support for multi-threaded debugging (planned for v2.1)

  • Line breakpoints: Conditional breakpoints not yet exposed via MCP (DAP supports it)

✅ Resolved from v1:

  • No stepping → Now available: Step in, step over, step out

  • sys.modules corruption → Fixed: DAP uses isolated processes

  • Python environment mismatch → Fixed: Uses target interpreter

See docs/roadmap.md for planned v2.1+ enhancements.

Contributing

  1. Fork the repository

  2. Create a feature branch (git checkout -b feature/amazing-feature)

  3. Make your changes with tests

  4. Run tests and linting (uv run pytest && uv run ruff check .)

  5. Commit changes (git commit -m 'Add amazing feature')

  6. Push to branch (git push origin feature/amazing-feature)

  7. Open a Pull Request

License

MIT License - see LICENSE file for details

Acknowledgments

Built with:

  • debugpy - Microsoft's Python debugger (DAP implementation)

  • MCP SDK - Model Context Protocol Python SDK

  • bdb/pdb - Python's standard debugger framework (legacy mode)

  • Pydantic - Data validation using Python type annotations

  • Typer - CLI framework built on Click

  • Rich - Beautiful terminal formatting

  • pytest - Testing framework

Available Tools

8 tools
sessions_breakpointA

Run to a breakpoint and capture local variables

Inputs: sessionId (required), file (required), line (required).

sessions_continueC

Continue execution to the next breakpoint

Inputs: sessionId (required), file (required), line (required).

sessions_createB

Create a new debug session for a Python script

Inputs: entry (required), pythonPath (required), args, env.

sessions_endC

End a debug session and clean up resources

Inputs: sessionId (required).

sessions_stateB

Get the current state of a debug session

Inputs: sessionId (required).

sessions_step_inB

Step into the next function call (requires active breakpoint)

Inputs: sessionId (required).

sessions_step_outB

Step out of the current function (requires active breakpoint)

Inputs: sessionId (required).

sessions_step_overB

Step over the current line (requires active breakpoint)

Inputs: sessionId (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose within the debug session lifecycle: create, end, state, breakpoint, continue, and three distinct step types. The descriptions specify unique actions like 'step into' vs 'step over', eliminating any ambiguity between tools.

    Naming Consistency5/5

    All tools follow a perfect 'sessions_verb' pattern (e.g., sessions_create, sessions_step_over). This consistent naming convention makes the tool set predictable and easy to understand at a glance.

    Tool Count5/5

    With 8 tools, this server provides a well-scoped set for debugging operations. It covers the essential debug session lifecycle (create, state, end) and core execution control (breakpoint, continue, step variations) without being overwhelming or sparse.

    Completeness5/5

    The tool set offers complete coverage for a debug session domain: creation, state monitoring, execution control (breakpoint, continue, step in/out/over), and cleanup. There are no obvious gaps; agents can fully manage debug sessions from start to finish.

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      A
      maintenance
      An MCP server and VS Code extension that enables AI clients to interactively debug code using breakpoints, execution control, and state inspection. It is language-agnostic and works with any debugger that supports VS Code's launch.json configurations.
      -
    • A
      license
      B
      quality
      D
      maintenance
      Enables coding agents to use a real debugger (Python via debugpy) for launching, attaching, setting breakpoints, stepping through code, inspecting stack frames, and evaluating expressions through MCP tools.
      12
      27
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to inspect debug state, control execution, and set breakpoints in VS Code by exposing the Debug Adapter Protocol as an MCP server.
      Apache 2.0