mcp-debugpy

mcp-debugpy is an MCP server that enables AI-assisted debugging of Python code using the debugpy adapter and the Debug Adapter Protocol. It exposes tools to run tests and read JSON-formatted results, along with direct DAP (Debug Adapter Protocol) control over a live debugpy session. This enables agents and chat surfaces to trigger test runs, inspect failures, and drive a running Python process through breakpoints, step commands, and variable inspection. The server is designed to be managed by MCP clients (e.g., VS Code or Claude), so you typically configure the server in your client rather than starting it manually.

From a usage perspective, you can invoke tool requests such as run_tests_json to execute the test suite and retrieve machine-readable failure data, or dap_launch to start and interact with a live debugpy session in your sample application. The repository includes a sample app with a deliberate bug to demonstrate failing tests and interactive debugging, along with helper scripts for configuring MCP clients and launching the DAP adapter flow. To integrate, register the MCP server with your MCP client configuration (paths may be project-specific) and then issue tool requests via your chat surface or IDE integration to control the debugging workflow.

Prerequisites:

• Python 3.8+ (recommended)
• A virtual environment tool (venv) or conda
• Git

Step-by-step installation:

1. Clone the repository git clone https://github.com/markomanninen/mcp-debugpy.git cd mcp-debugpy

2. Create and activate a virtual environment python -m venv .venv source .venv/bin/activate # macOS/Linux .venv\Scripts\activate # Windows

3. Install runtime and development dependencies pip install -r requirements.txt pip install -r requirements-dev.txt

4. Install the package in editable mode (for development) pip install -e '.[dev]'

5. Optional: install pre-commit hooks and run CI checks locally pip install pre-commit pre-commit install pre-commit run --all-files

6. Run the MCP server directly (for manual testing, not required in normal usage) python src/mcp_server.py

7. If you are configuring MCP clients (VS Code/Claude), follow the docs in docs/mcp_usage.md to register the server and its tool set.

Prereqs for testing and debugging live adapters are already included via requirements-dev.txt.

Tips and notes:

• In normal usage, MCP clients manage the server process automatically. You typically do not start python src/mcp_server.py manually; instead, configure it in your MCP client so it launches on demand.
• The repository demonstrates tools like run_tests_json for machine-readable test results and dap_launch for starting a debugpy session with specified breakpoints.
• If you encounter environment-related issues, ensure PYTHONPATH includes the src directory (as shown in the configuration examples) so modules are importable.
• When testing locally, you can use the sample app and tests under src/sample_app to verify test reporting and DAP control flows.
• For code quality and type checking, the project uses pre-commit hooks and CI that run ruff, black, mypy, and pytest. Consider enabling these locally for a smoother workflow.
• The MCP server is designed to be managed by clients like VS Code or Claude Desktop; manual CLI usage is primarily for protocol development and debugging.