Skip to main content
Glama

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.

Related MCP server: debugpy-mcp

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.

Available Tools

11 tools
clear_breakpointA
Idempotent

Clear a breakpoint for a file and line number.

Inputs: line (required), filepath (required). Returns: object

continue_executionA

Resume execution and wait for the next stop or exit event.

Inputs: no named parameters. Returns: object

end_sessionA

End the active debug session and terminate the debuggee.

Inputs: no named parameters. Returns: object

evaluate_expressionA
Read-only

Evaluate an expression in the top stack frame.

Inputs: expression (required). Returns: object

get_stack_traceA
Read-onlyIdempotent

Return the current stack trace for the active thread.

Inputs: no named parameters. Returns: object

get_variable_detailsA
Read-only

Evaluate a variable name in the top stack frame.

Inputs: variable_name (required). Returns: object

launch_debuggerA

Launch a Python script under debugpy and wait until execution pauses.

Inputs: script_path (required), cwd, args, console, +3 more. Returns: object

set_breakpointB
Idempotent

Set a breakpoint for a file and line number.

Inputs: line (required), filepath (required). Returns: object

step_intoA

Step into the current call and wait for the next stop.

Inputs: no named parameters. Returns: object

step_outA

Step out of the current frame and wait for the next stop.

Inputs: no named parameters. Returns: object

step_overA

Step over the current line and wait for the next stop.

Inputs: no named parameters. Returns: object

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 11 tools

    Disambiguation4/5

    Most tools are clearly distinct, but evaluate_expression and get_variable_details both operate on the top stack frame and could be confused (expression vs. variable name). The step commands are well differentiated, and the rest of the tools have unambiguous purposes.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun or verb_adverb pattern (launch, set, clear, step, get, evaluate, end, continue). The naming is predictable and intuitive, with no mixed conventions.

    Tool Count5/5

    11 tools is well-scoped for a debugger server. Each tool serves a clear, essential purpose in the debugging workflow without redundancy or bloat.

    Completeness4/5

    The tool set covers the core debugger lifecycle: launch, breakpoints, stepping, stack inspection, expression evaluation, and termination. Minor gaps exist (e.g., listing all variables, exception breakpoints) but are not critical for typical workflows.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to perform interactive Python debugging with breakpoints, step execution, and variable inspection using the Debug Adapter Protocol (DAP) through an MCP server interface.
      8
      1
      MIT
    • F
      license
      D
      quality
      D
      maintenance
      An MCP server that enables agents to attach debugpy to running Python processes inside Docker containers for enhanced debugging and inspection. It provides tools for container autodiscovery, process injection, and generating breakpoint plans based on logs and metadata.
      8
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that provides a real debugger via the Debug Adapter Protocol, exposing a single 'debug' tool to launch/attach, control execution, and inspect program state across gdb, lldb, debugpy, and more.
      MIT