AI导哈

Python调试器接口

python-debugger-mcp是一个为Claude和其他LLMs提供Python调试器（pdb）工具集的服务，通过Model Context Protocol (MCP)实现。

  • by Wangshengyang2004
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 Wangshengyang2004/python-debugger-mcp

使用说明

python调试器mcp:Claude/LLM的python调试器接口

python调试器mcp提供了通过模型上下文协议（mcp）将python的调试器（pdb）与Claude和其他LLM一起使用的工具。其灵感来源于 调试健身房 微软通过提供对python调试器的编码代理访问，在各种编码基准测试中取得了进展。

基于 mcp-pdb 具有显著增强功能：

功能 mcp-pdb python调试器mcp
工具数量 16 24
堆栈导航 - navigate_Stack，get_Stack_trace
条件断点 - set_breakpoint_with_condition
临时断点 - 设置临时断点
断点管理 - 启用断点、禁用断点、忽略断点
变量监视 - set_display、list_display和clear_display
代码检查 - list_source，get_function_args，get_turn_value，get_variable_type
死后调试 - enter_Postmortem_mode
测试 - 综合单元测试
多语言文档 - 英语+中文（README_CN.md）
IDE支持 有限 克劳德代码、游标、OpenCode、Windsurf

中文文档

⚠️ 安全警告

此工具通过调试器执行Python代码。仅在受信任的环境中使用。

安装

配合使用效果最佳 紫外线

克劳德代码

# Install the MCP server directly from GitHub
claude mcp add python-debugger-mcp -- uv run --with git+https://github.com/Wangshengyang2004/python-debugger-mcp python-debugger-mcp

# Alternative: Install with specific Python version
claude mcp add python-debugger-mcp -- uv run --python 3.13 --with git+https://github.com/Wangshengyang2004/python-debugger-mcp python-debugger-mcp

# Note: The -- separator is required for Claude Code CLI

帆板运动

{
  "mcpServers": {
    "python-debugger-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "git+https://github.com/Wangshengyang2004/python-debugger-mcp",
        "python-debugger-mcp"
      ]
    }
  }
}

光标

方法1：使用mcp.json（推荐）

创建或编辑 ~/.cursor/mcp.json （全球）或 .cursor/mcp.json （项目特定）：

{
  "mcpServers": {
    "python-debugger-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "git+https://github.com/Wangshengyang2004/python-debugger-mcp",
        "python-debugger-mcp"
      ]
    }
  }
}

然后重新启动Cursor以加载MCP服务器。

方法2：一键安装

打开光标设置>MCP>单击“+添加MCP服务器”并粘贴：

uv run --with git+https://github.com/Wangshengyang2004/python-debugger-mcp python-debugger-mcp

开源代码

OpenCode基于VS Code架构构建，同样支持MCP服务器。

方法1：使用JSON设置

  1. 打开命令面板（Ctrl+Shift+P）
  2. 运行“首选项：打开设置（JSON）”
  3. 添加以下配置：
{
  "mcpServers": {
    "python-debugger-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "git+https://github.com/Wangshengyang2004/python-debugger-mcp",
        "python-debugger-mcp"
      ]
    }
  }
}

方法2：使用.mcp.json文件

创建 ~/.opencode/mcp.json 对于全局设置：

{
  "mcpServers": {
    "python-debugger-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "git+https://github.com/Wangshengyang2004/python-debugger-mcp",
        "python-debugger-mcp"
      ]
    }
  }
}

然后重新启动OpenCode以应用更改。

可用工具

会话管理

工具 说明
start_debug(file_path, use_pytest, args) 启动Python文件的调试会话
restart_debug() 重新启动当前调试会话
end_debug() 结束当前调试会话
get_debug_status() 显示调试会话的当前状态

执行控制

工具 说明
send_pdb_command(command) 发送原始PDB命令

堆栈导航

工具 说明
navigate_stack(direction, count) 向上/向下移动堆栈跟踪
get_stack_trace() 打印当前堆栈跟踪

断点

工具 说明
set_breakpoint(file_path, line_number) 在特定行设置断点
set_breakpoint_with_condition(file, line, condition) 使用条件设置断点
set_temporary_breakpoint(file, line) 设置临时断点（首次点击后删除）
enable_breakpoint(bp_number) 启用已禁用的断点
disable_breakpoint(bp_number) 禁用断点
ignore_breakpoint(bp_number, count) 忽略N次点击的断点
clear_breakpoint(file_path, line_number) 清除断点
list_breakpoints() 列出所有当前断点

变量观察

工具 说明
examine_variable(variable_name) 获取变量的详细信息
set_display(expression) 添加表达式以自动显示
list_displays() 列出所有活动的显示表达式
clear_display(expression_or_id) 删除显示表达式

代码检查

工具 说明
list_source(long_list) 列出当前断点周围的源代码
get_function_args() 打印函数参数
get_return_value() 打印上次函数调用的返回值
get_variable_type(expression) 变量的打印类型

尸检调试

工具 说明
enter_postmortem_mode() 进入事后调试模式

常见PDB命令

命令 描述
n 下一行（跳过）
s 进入功能
c 继续执行
r 从当前函数返回
p variable 打印变量值
pp variable 漂亮的打印变量
b file:line 设置断点
cl num 清除断点
l 列出源代码
q 退出调试

特性

  • 具有自动虚拟环境检测功能的项目感知调试
  • 支持直接Python调试和基于pytest的调试
  • 会话之间的自动断点跟踪和恢复
  • 与UV包管理器配合使用
  • 具有类型信息和属性列表的变量检查
  • 条件断点和临时断点
  • 可变手表表情（显示）
  • 烟囱导航和检查
  • 死后调试支持

成功案例

调试2048游戏逻辑

使用python调试器mcp调试一个2048游戏项目，并成功发现并修复了一个错误：

发现Bug：In game.py，the _check_game_over() 当空单元格存在时，该方法很早就返回了，但忘记了设置 game_over = False。这导致游戏错误地报告“游戏结束”，即使有空单元格可用。

MCP如何提供帮助:

  1. 使用设置断点 set_breakpoint() 检查游戏状态
  2. 使用以下代码逐步完成 send_pdb_command("n")
  3. 检查以下变量 game.board 和 examine_variable()
  4. 使用清除和管理断点 clear_breakpoint()
  5. 验证修复是否正常工作

结果：修复了错误-现在可以正确检测游戏结束状态。

故障排除

Claude代码安装问题

如果您遇到以下错误：

MCP server "python-debugger-mcp" Connection failed: spawn /Users/xxx/.local/bin/uv run --python 3.13 --with python-debugger-mcp python-debugger-mcp ENOENT

确保包括 -- 使用时使用分离器 claude mcp add:

# ✅ Correct
claude mcp add python-debugger-mcp -- uv run --with git+https://github.com/Wangshengyang2004/python-debugger-mcp python-debugger-mcp

# ❌ Incorrect (missing --)
claude mcp add python-debugger-mcp uv run --with git+https://github.com/Wangshengyang2004/python-debugger-mcp python-debugger-mcp

要验证您的安装：

# Check if python-debugger-mcp is listed
claude mcp list | grep python-debugger-mcp

# Check server status in Claude Code
# Type /mcp in Claude Code to see connection status

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

致谢

相关 MCP