Debug-MCP Server

Debug-MCP provides a production-ready Python debugging workflow exposed through a clean programmatic API and a command-line interface, designed to integrate with AI assistants and development tools. It enables breakpoint-based debugging via the Debug Adapter Protocol (DAP) with isolated processes for safety, while offering an MCP server interface for seamless automation and tooling integration.

How to use

You will use an MCP client to connect to the Debug-MCP server and perform debugging tasks such as starting a session, hitting breakpoints, inspecting locals, and continuing execution. The server runs as an MCP stdio endpoint, so you interact with it through the provided CLI or the MCP SDK integration. Typical workflows include starting a session for a target script, setting a breakpoint, and stepping through code with automatic environment handling and isolated execution to prevent module contamination.

How to install

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

# Create a virtual environment (recommended)
uv venv

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

Configuration and usage patterns

The server supports both a CLI workflow and an MCP-based integration. Use the CLI for interactive debugging and the MCP endpoint when you want AI assistants or Copilot to drive debugging sessions. You can manage sessions, run to breakpoints, inspect locals, and continue execution, all within isolated subprocesses that prevent cross-run contamination.

Copilot integration and MCP server configuration

To enable Copilot to interact with Debug-MCP, configure an MCP server entry that points to the local MCP server. The following configuration runs the MCP server via the CLI wrapper and passes the workspace context to the server. Ensure the environment variable PYTHONUNBUFFERED is set to 1 for clean I/O.

{
  "mcpServers": {
    "python_debug": {
      "command": "uv",
      "args": ["run", "mcp-debug-server", "--workspace", "${workspaceFolder}"],
      "env": {"PYTHONUNBUFFERED": "1"}
    }
  }
}

API and CLI usage overview

CLI operators can start a debug session, run to a breakpoint, and inspect locals, all from the terminal. If you are integrating with code, you can use the MCP SDK to create sessions, issue breakpoints, and manage session lifecycle programmatically.

Safety and responsibilities

Debug-MCP executes user code in a sandboxed subprocess with configurable timeouts and output limits. Paths are validated to be project-relative, the working directory is locked to the workspace root, and the debuggee has no network access. Use caution when debugging untrusted code, and prefer trusted targets when enabling advanced features.

Notes and best practices

• Prefer DAP-based debugging for reliability and full feature support (step in/over/out, breakpoints, and variable inspection).
• When using Copilot or AI assistants, run in a dedicated workspace to avoid cross-project contamination.
• Monitor session timeouts and output limits to prevent resource exhaustion during long-running debug sessions.

Troubleshooting tips

If breakpoints are not hit, verify that the target script path is correct, the interpreter environment matches the project, and the server is running in an isolated subprocess. Check that the MCP server command and arguments match your local setup and that PYTHONUNBUFFERED is set where applicable.

Notes on future improvements

The debugging system is designed to evolve with enhanced DAP capabilities, additional breakpoint types, and more robust environment handling. Expect improvements in multi-target debugging, extended variable inspection, and richer error visibility in upcoming versions.

Security considerations

Only run debug targets that are trusted. The isolated subprocess approach minimizes risk, but you should still validate code paths and avoid exposing sensitive data through breakpoints or locals during debugging sessions.

What’s included in this setup

• A Python debugging tool exposed via an MCP server and a CLI for interactive use.
• DAP-based production debugging with isolated execution.
• Session lifecycle management with timeout protection.
• Safety and environment-aware operation that uses the target project interpreter.

Available tools

start_session

Create and initialize a new debugging session for a target script, returning a session identifier and initial state.

run_to_breakpoint

Run the debugged program until it hits the specified breakpoint, returning paused state and local variables.

continue_execution

Resume execution to the next breakpoint or end of program, updating session state accordingly.

end_session

Terminate an active debugging session and clean up resources.

state_query

Query current status of a debugging session, including current location and session health.

set_breakpoint

Set breakpoints in the target script to pause execution at specific lines or conditions.