python-dap-mcp

python-dap-mcp is an MCP server that exposes Python debugging tools backed by debugpy.

It gives an MCP client a focused Python debugging surface for local scripts:

• Launch a Python script under debugpy
• Set and clear breakpoints by file and line
• Continue execution or step over, into, and out
• Inspect the active stack trace
• Evaluate expressions in the top frame
• Read variable details from the active frame
• End the debug session cleanly

The server is intentionally narrow. It runs over stdio, uses debugpy as the underlying adapter, and is designed for local trusted development environments.

What This Server Does

This repository packages a single MCP server command, python-dap-mcp.

When an MCP client connects to it, the server exposes these tools:

• launch_debugger
• set_breakpoint
• clear_breakpoint
• continue_execution
• step_over
• step_into
• step_out
• get_stack_trace
• evaluate_expression
• get_variable_details
• end_session

The server resolves relative paths from its project root and launches the debug target with debugpy.adapter.

When To Use It

This server is useful when an MCP client needs to inspect or control a real Python process instead of only reading source code.

Common use cases:

• Reproducing a bug and stopping at a specific line
• Inspecting locals at a breakpoint
• Evaluating expressions against a live frame
• Stepping through control flow in a small script or test fixture
• Building agent workflows that need real debugger feedback

Install from GitHub

Run it directly from GitHub with uvx:

uvx --from git+https://github.com/MikeWinkelmannXL2/python-dap-mcp@v0.1.0 python-dap-mcp

Install it persistently with uv tool install:

uv tool install git+https://github.com/MikeWinkelmannXL2/python-dap-mcp@v0.1.0

If you want the latest branch state instead of a tag, replace @v0.1.0 with @main.

To run from a private fork or private repository, use the SSH form:

uvx --from git+ssh://git@github.com/MikeWinkelmannXL2/python-dap-mcp.git@v0.1.0 python-dap-mcp

Integration

Codex

Codex supports local stdio MCP servers through the CLI and ~/.codex/config.toml.

Add this server with the Codex CLI:

codex mcp add python-debugger -- \
  uvx --from git+https://github.com/MikeWinkelmannXL2/python-dap-mcp@v0.1.0 python-dap-mcp

Verify that Codex sees it:

codex mcp list

Equivalent ~/.codex/config.toml entry:

[mcp_servers.python-debugger]
command = "uvx"
args = ["--from", "git+https://github.com/MikeWinkelmannXL2/python-dap-mcp@v0.1.0", "python-dap-mcp"]

GitHub Copilot CLI

Copilot CLI can add MCP servers interactively with /mcp add, or you can edit ~/.copilot/mcp-config.json directly.

Recommended ~/.copilot/mcp-config.json entry:

{
  "mcpServers": {
    "python-debugger": {
      "type": "local",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/MikeWinkelmannXL2/python-dap-mcp@v0.1.0",
        "python-dap-mcp"
      ],
      "env": {},
      "tools": ["*"]
    }
  }
}

If you prefer the interactive flow, run /mcp add inside Copilot CLI and use:

• Server name: python-debugger
• Server type: Local or STDIO
• Command: uvx
• Args: --from git+https://github.com/MikeWinkelmannXL2/python-dap-mcp@v0.1.0 python-dap-mcp
• Tools: *

Claude Code

Claude Code supports local stdio MCP servers directly from its CLI.

Add this server with:

claude mcp add python-debugger -- \
  uvx --from git+https://github.com/MikeWinkelmannXL2/python-dap-mcp@v0.1.0 python-dap-mcp

Verify it:

claude mcp get python-debugger

If you prefer JSON-based setup, the equivalent server definition is:

{
  "type": "stdio",
  "command": "uvx",
  "args": [
    "--from",
    "git+https://github.com/MikeWinkelmannXL2/python-dap-mcp@v0.1.0",
    "python-dap-mcp"
  ],
  "env": {}
}

If You Install The Tool Globally

If python-dap-mcp is already installed on the machine, each client can point directly to the executable instead of uvx:

command: python-dap-mcp
args: []

Typical Workflow

A normal debugger flow through MCP looks like this:

1. Call set_breakpoint with a source file and 1-based line number.
2. Call launch_debugger with the script path and optional arguments.
3. When execution stops, call get_stack_trace, evaluate_expression, or get_variable_details.
4. Call continue_execution or one of the step tools.
5. Call end_session when you are done.

Example sequence:

set_breakpoint("app.py", 42)
launch_debugger("app.py", stop_on_entry=false)
get_stack_trace()
evaluate_expression("user_id")
continue_execution()
end_session()

Tool Semantics

• launch_debugger starts one active session at a time. A second launch is rejected until the first session ends.
• console is intentionally limited to internalConsole.
• Breakpoints can be set before launch. They are synchronized when the debug session starts.
• Expression evaluation runs in the top stack frame of the currently stopped thread.
• Relative paths are resolved from the server project root.

Requirements

• Python 3.13+
• A local environment where the server is allowed to launch Python processes
• A trusted workspace. This server can execute code and evaluate expressions inside the debuggee context

Development

Run the full test suite:

env UV_CACHE_DIR=/tmp/uv-cache uv run --extra dev pytest

Build distributable artifacts with the uv build backend:

env UV_CACHE_DIR=/tmp/uv-cache uv build

Run the server from the repository:

uv run python -m debug_server

Run it through the installed package entrypoint:

uv run python -m python_dap_mcp

Security

This server can:

• Launch local Python programs
• Pause and resume execution
• Evaluate expressions in a live frame
• Expose runtime state from the debuggee process

That makes it useful, but also high-trust. Only install and run it in environments you control and only connect trusted MCP clients to it.