# 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`:

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

Install it persistently with `uv tool install`:

```sh
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:

```sh
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:

```sh
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:

```sh
codex mcp list
```

Equivalent `~/.codex/config.toml` entry:

```toml
[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:

```json
{
  "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:

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

Verify it:

```sh
claude mcp get python-debugger
```

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

```json
{
  "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`:

```text
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:

```text
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:

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

Build distributable artifacts with the uv build backend:

```sh
env UV_CACHE_DIR=/tmp/uv-cache uv build
```

Run the server from the repository:

```sh
uv run python -m debug_server
```

Run it through the installed package entrypoint:

```sh
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.