GDB MCP 服务器

一个提供给AI助手程序化访问GDB调试会话的MCP（模型上下文协议）服务器。这使得AI模型能够像VS Code和CLion这样的IDE一样与调试器交互，使用GDB/MI（机器接口）协议。

功能

• 完整的GDB控制：启动会话、执行命令、控制程序执行
• 线程分析：检查线程、获取回溯、分析线程状态
• 断点管理：设置条件断点、临时断点
• 变量检查：评估表达式、检查变量和寄存器
• 核心转储分析：加载并分析带有自定义初始化的核心转储
• 灵活的初始化：在启动时运行GDB脚本或命令

架构

此服务器使用**GDB/MI（机器接口）**协议，这是专业IDE使用的同一接口。它提供了：

• 结构化、机器可解析的输出
• 对GDB调试能力的完全访问
• 可靠的命令执行和响应处理

安装

先决条件

• Python 3.10 或更高版本
• 已安装并添加到PATH中的GDB

快速开始

# 如果需要，请安装pipx
python3 -m pip install --user pipx
python3 -m pipx ensurepath

# 安装gdb-mcp-server
cd /path/to/gdb-mcp
pipx install .

对于其他安装方法（虚拟环境、手动设置），请参见INSTALL.md。

配置

Claude Desktop

在你的Claude Desktop配置文件中添加以下内容：

位置：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

配置：

{
  "mcpServers": {
    "gdb": {
      "command": "gdb-mcp-server"
    }
  }
}

对于其他安装方法和MCP客户端，请参见INSTALL.md。

环境变量

GDB MCP服务器支持以下环境变量：

GDB_PATH

指定要使用的GDB可执行文件的路径。这在以下情况下很有用：

• 安装了多个GDB版本
• GDB安装在非标准位置
• 想要使用自定义或修补过的GDB构建

默认值：gdb（通过系统PATH解析）

示例：

export GDB_PATH=/usr/local/bin/gdb-13.2
gdb-mcp-server

注意：如果同时指定了gdb_start_session工具中的gdb_path参数，它将覆盖这个环境变量。

GDB_MCP_LOG_LEVEL

设置服务器的日志级别。

默认值：INFO 选项：DEBUG, INFO, WARNING, ERROR, CRITICAL

示例：

export GDB_MCP_LOG_LEVEL=DEBUG
gdb-mcp-server

可用工具

GDB MCP服务器提供了21个工具来控制GDB调试会话：

会话管理：

• gdb_start_session - 使用可选初始化启动新的GDB会话
• gdb_execute_command - 执行任何GDB命令（CLI或MI）
• gdb_get_status - 获取当前会话状态
• gdb_stop_session - 停止当前会话

线程及帧导航：

• gdb_get_threads - 列出所有线程
• gdb_select_thread - 选择特定线程
• gdb_get_backtrace - 获取线程的堆栈跟踪
• gdb_select_frame - 选择特定堆栈帧
• gdb_get_frame_info - 获取关于当前帧的信息

断点管理：

• gdb_set_breakpoint - 设置带可选条件的断点
• gdb_list_breakpoints - 列出所有断点，带有结构化数据
• gdb_delete_breakpoint - 根据编号删除断点
• gdb_enable_breakpoint - 启用断点
• gdb_disable_breakpoint - 禁用断点

执行控制：

• gdb_continue - 继续执行
• gdb_step - 进入函数
• gdb_next - 跨越函数
• gdb_interrupt - 暂停正在运行的程序

数据检查：

• gdb_evaluate_expression - 评估表达式
• gdb_get_variables - 获取局部变量
• gdb_get_registers - 获取CPU寄存器

有关每个工具的详细文档，包括参数、返回值和示例，请参见TOOLS.md。

使用示例

示例1：分析核心转储

用户："加载位于/tmp/core.12345的核心转储，将sysroot设置为/opt/sysroot，并告诉我崩溃时有多少线程。"

AI操作：

1. 使用初始化命令启动会话：

{
  "init_commands": [
    "file /path/to/executable",
    "core-file /tmp/core.12345",
    "set sysroot /opt/sysroot"
  ]
}

2. 获取线程：gdb_get_threads
3. 报告："崩溃时有8个线程。"

示例2：条件断点调查

用户："在process_data处设置断点，但仅当count变量大于100时，然后继续执行。"

AI操作：

1. 设置条件断点：

{
  "location": "process_data",
  "condition": "count > 100"
}

2. 继续执行：gdb_continue
3. 当命中时，检查状态

有关更详细的使用示例和工作流程，请参见examples/USAGE_GUIDE.md和examples/README.md。

高级用法

自定义GDB初始化脚本

创建一个.gdb文件，其中包含你的设置命令：

# setup.gdb
file /path/to/myprogram
core-file /path/to/core

# 设置符号路径
set sysroot /opt/sysroot
set solib-search-path /opt/libs:/usr/local/lib

# 方便设置
set print pretty on
set print array on
set pagination off

然后使用它：

{
  "init_commands": ["source setup.gdb"]
}

Python初始化脚本

你也可以使用GDB的Python API：

# init.py
import gdb
gdb.execute("file /path/to/program")
gdb.execute("core-file /path/to/core")
# 自定义分析

使用：

{
  "init_commands": ["source init.py"]
}

处理正在运行的进程

虽然此服务器主要与核心转储和可执行文件一起工作，但你可以附加到正在运行的进程中：

{
  "init_commands": [
    "attach 12345"  // 正在运行的进程的PID
  ]
}

注意：这需要适当的权限（通常是root或同一用户）。

故障排除

常见问题

未找到GDB

which gdb
gdb --version

超时错误/命令无响应

程序很可能仍在运行！当程序正在运行时，GDB忙于执行，不会响应其他命令。

解决方案：使用gdb_interrupt暂停正在运行的程序，然后其他命令将起作用。

程序状态：

• 未启动：使用gdb_execute_command与"run"或"start"
• 正在运行：程序正在执行 - 使用gdb_interrupt暂停它
• 暂停（在断点处）：使用gdb_continue，gdb_step，gdb_next，检查变量
• 已完成：程序已退出 - 如需重新启动，请使用"run"

缺少调试符号

始终检查gdb_start_session响应中的warnings字段！编译程序时使用-g标志。

有关详细的故障排除、安装问题和其他解决方案，请参见INSTALL.md。

工作原理

1. GDB/MI协议：服务器使用机器接口（MI）协议与GDB通信，这是IDE使用的同一接口。
2. pygdbmi库：我们使用优秀的pygdbmi库来处理低级协议细节和响应解析。
3. MCP集成：服务器将GDB功能作为MCP工具公开，允许AI助手：
   • 理解可用的调试操作
   • 使用正确的参数执行命令
   • 解释结构化的响应
4. 会话管理：每个服务器实例维护一个单独的GDB会话，允许跨多个工具调用的状态化调试。

贡献

欢迎贡献！改进领域：

• 额外的GDB命令（例如，观察点、内存检查）
• 更好的错误处理和恢复
• 增强的输出格式化

许可证

MIT

参考资料

• GDB机器接口（MI）
• pygdbmi文档
• 模型上下文协议