GDB调试服务器

GDB MCP Server

Language: Chinese | English

Overview

A server that can call GDB through MCP tools, providing session management, target/process control, breakpoints, execution control, stack and variables, expressions, memory read/write, and event polling.

Environmental Requirements

• Ubuntu Linux， install gdb(>=9.0).
• Python 3.10+。

Configure config. json

• Location: Project Root Directory config.json, automatically loaded at runtime, or through environment variables GDB_MCP_CONFIG=/path/to/config.json appoint.

• Key fields:

  • log_dir: Log directory, default logs(Automatically created when it does not exist).
  • server_host/server_portTCP listening address and port (used for --listen Mode).
  • allowed_root: Adjustable root directory restrictions (optional to enhance security).
  • GDB does not require Python binding path configuration; Only system installation is required gdb Just enough.
  • project_rootThe absolute path of the project root directory (such as $(pwd)）.
  • src_pathSource code path (usually <project_root>/src）.
  • client.target_binExample client default debugged executable path; Environment variables can also be used TARGET_BIN Covering.

• How to find the path:

  • lldb -P Get Python path (preferred).
  • which python3 Or Xcode .../usr/bin/python3 set as python_executable.
  • xcode-select -p get ${DEVROOT}Add the above two types of Framework paths framework_paths.
  • Fill in the remaining fields according to the actual path of the machine.

security configuration

• GDB_MCP_ALLOW_LAUNCH=1 allow launch
• GDB_MCP_ALLOW_ATTACH=1 allow attach
• GDB_MCP_ALLOWED_ROOT=/path/to/dir Restricted debuggable path (optional)

Run (network mode TCP)

• Start the server:PYTHONPATH=src GDB_MCP_ALLOW_LAUNCH=1 GDB_MCP_ALLOWED_ROOT=$(pwd)/examples/client/c_test/hello PYTHONUNBUFFERED=1 python3 -u -m gdb_mcp_server.mcp.server --listen 127.0.0.1:8765
• Example:
  • Create a session: {"id":"1","method":"initialize","params":{}}
  • Create goal: {"id":"2","method":"createTarget","params":{"sessionId":"<SID>","file":"/path/app"}}
  • Start process: {"id":"3","method":"launch","params":{"sessionId":"<SID>","args":[]}}
  • Polling event: {"id":"4","method":"pollEvents","params":{"sessionId":"<SID>","limit":32}}
    • pass pollEvents Get event list, example type:
      • targetCreated: Goal Creation
      • processLaunched/processAttachedProcess startup or attachment
      • processStateChangedProcess state changes (running/stopped/exported, etc.)
      • breakpointSet/breakpointHitBreakpoint setting and hit (including thread and frame information)
      • stdout/stderrProcess output capture

Client Example (Network Mode Only)

• Example client:
  • entrance:MCP_HOST=127.0.0.1 MCP_PORT=8765 python3 examples/client/run_debug_flow.py
  • preparecd examples/client/c_test/hello && cc -g -O0 -o hello hello.c And set it up TARGET_BIN=$(pwd)/hello

One-key start

• Building example objectives:cd examples/client/c_test/hello && cc -g -O0 -Wall -Wextra -o hello hello.c
• Start the server:PYTHONPATH=src GDB_MCP_ALLOW_LAUNCH=1 GDB_MCP_ALLOWED_ROOT=$(pwd)/examples/client/c_test/hello PYTHONUNBUFFERED=1 python3 -u -m gdb_mcp_server.mcp.server --listen 127.0.0.1:8765
• Start the client:TARGET_BIN=$(pwd)/examples/client/c_test/hello/hello MCP_HOST=127.0.0.1 MCP_PORT=8765 python3 examples/client/run_debug_flow.py

Frequently Asked Questions

• No module named gdbPlease confirm that the system has been installed gdb And executable; This project uses pygdbmi Call gdb through the MI interface without the need import gdb Python binding.
• ptrace 权限限制In a WSN/container/strict security policy environment,run May prompt Could not trace the inferior or ptrace: 不允许的操作 And exit 127. solve:
  • Ubuntu/WSLs: Execution sudo sysctl kernel.yama.ptrace_scope=0(Temporary), or written /etc/sysctl.d/10-ptrace.conf Persistent and sudo sysctl --system.
  • Docker: Using --cap-add=SYS_PTRACE Running containers; Or relax inside the container ptrace_scope.
  • Restricted host: Contact the administrator to relax debugging permissions or run as root.