mcp-gdb

mcp-gdb

中文文档 | English

A Model Context Protocol (MCP) server for GDB — core dump analysis, remote debugging, and direct program debugging on Linux.

Built with Rust and Tokio for async I/O. Ships as a single executable with no runtime dependencies.

Features

• Core dump analysis — Open core files, inspect threads, stack traces, and shared libraries
• Remote debugging — Connect to gdbserver targets via host:port
• Direct program debugging — Launch executables under GDB, set breakpoints, step through code, inspect variables
• Session management — Multiple concurrent debug sessions with automatic reuse
• Configurable timeouts — Separate timeouts for initialization (symbol loading) and command execution
• Debuginfod control — Option to disable automatic symbol downloading for restricted networks
• Stripped binary support — Configure debug_info_directory and sysroot for separated debug info

Prerequisites

• Linux
• GDB

If GDB is not installed:

# Debian/Ubuntu
sudo apt install gdb

# RHEL/CentOS/Fedora
sudo dnf install gdb

# Arch
sudo pacman -S gdb

The server auto-discovers GDB from PATH and common Linux paths (/usr/bin/gdb, /usr/local/bin/gdb).

Installation

From source

git clone https://github.com/FlorentinoJink/mcp-gdb.git
cd mcp-gdb
cargo build --release

Binary: target/release/mcp-gdb

Configuration

VS Code / Kiro

.vscode/mcp.json:

{
  "servers": {
    "mcp-gdb": {
      "type": "stdio",
      "command": "/path/to/mcp-gdb",
      "args": []
    }
  }
}

Claude Desktop / Cline / Other MCP Clients

{
  "mcpServers": {
    "mcp-gdb": {
      "command": "mcp-gdb",
      "args": []
    }
  }
}

Environment Variables

Variable	Description	Default
GDB_PATH	Custom path to GDB executable	Auto-discovered
MCP_GDB_TIMEOUT	Command execution timeout (seconds)	30
MCP_GDB_INIT_TIMEOUT	Initialization timeout for symbol loading (seconds)	120
MCP_GDB_VERBOSE	Verbose logging (true/false)	false
MCP_GDB_DISABLE_DEBUGINFOD	Disable debuginfod automatic symbol downloading (true/false)	false

CLI Options

mcp-gdb [OPTIONS]

  --timeout <SECONDS>          Command execution timeout (default: 30)
  --init-timeout <SECONDS>     Initialization timeout (default: 120)
  --verbose                    Enable verbose logging
  --disable-debuginfod         Disable debuginfod automatic symbol downloading

Tools

Tool	Description
open_gdb_core	Open and analyze a Linux core dump file
open_gdb_remote	Connect to a gdbserver remote debugging target
launch_debug	Launch a program under GDB for debugging
run_gdb_cmd	Execute a GDB command in an existing session
close_gdb_core	Close a core dump analysis session
close_gdb_remote	Close a remote debugging session
close_debug	Close a launch debug session and terminate the program
list_core_dumps	List core dump files in a directory

Usage Examples

Core Dump Analysis

Analyze the core dump at /tmp/core.12345

Remote Debugging

Connect to gdbserver at 192.168.1.100:1234 and show the current state

Direct Program Debugging

Launch a program, set breakpoints, step through code:

Launch /home/user/myapp for debugging

Then use run_gdb_cmd to control execution:

break main       — Set breakpoint at main
run              — Start execution
next             — Step over
step             — Step into
bt               — Backtrace
info locals      — View local variables
list             — Show source at current location
continue         — Continue execution

The launch_debug tool supports optional parameters:

Parameter	Type	Description
program_path	string	Path to the executable to debug (required)
arguments	string[]	Command line arguments
working_directory	string	Working directory
debug_info_directory	string	Path to separated debug info (for stripped binaries)
source_path	string	Source file search path
include_backtrace	boolean	Include initial backtrace
include_modules	boolean	Include shared library list

The open_gdb_core tool supports optional parameters:

Parameter	Type	Description
core_dump_path	string	Path to the core dump file (required)
executable_path	string	Path to the executable (for symbol loading)
include_backtrace	boolean	Include backtrace output
include_threads	boolean	Include thread list
include_shared_libraries	boolean	Include shared library list
debug_info_directory	string	Path to separated debug info directory
sysroot	string	Sysroot path for cross-debugging

Close a Session

Close the debug session for /home/user/myapp

Troubleshooting

GDB not found — Install via your package manager (apt install gdb, dnf install gdb) or set GDB_PATH to your GDB location.

Symbol downloading blocks GDB — Use --disable-debuginfod or set MCP_GDB_DISABLE_DEBUGINFOD=true to prevent GDB from downloading symbols over the network.

Command timeout — Increase with --timeout 60 or MCP_GDB_TIMEOUT=60. Large core dumps and symbol loading may need higher MCP_GDB_INIT_TIMEOUT.

ptrace errors in containers — If running in Docker/containers, add --cap-add=SYS_PTRACE to your docker run command. For VMs like OrbStack, ptrace may have limited support.

Stripped binaries — Use the debug_info_directory parameter to point to separated debug info (typically /usr/lib/debug/). Install debug symbol packages: apt install <package>-dbg or dnf debuginfo-install <package>.

Related

• mcp-windbg — MCP server for Windows debugging (WinDbg/CDB)
• Model Context Protocol
• GDB Documentation

License

AGPL-3.0-or-later