GDB MCP Server

An MCP (Model Context Protocol) server that provides AI assistants with programmatic access to GDB debugging sessions. This allows AI models to interact with debuggers in the same way IDEs like VS Code and CLion do, using the GDB/MI (Machine Interface) protocol.

Features

• Full GDB Control: Start sessions, execute commands, control program execution
• Thread Analysis: Inspect threads, get backtraces, analyze thread states
• Breakpoint Management: Set conditional breakpoints, temporary breakpoints
• Hardware Breakpoints: Use CPU debug registers when software breakpoints are not suitable
• Multi-line Commands: Send commands, define, python, and other GDB command blocks
• Blocking Execution Control: run, continue, step, next, and finish wait until the target stops
• Variable Inspection: Evaluate expressions, inspect variables and registers
• Core Dump Analysis: Load and analyze core dumps with custom initialization
• Flexible Initialization: Run GDB scripts or commands on startup

Fixes in This Fork

This fork focuses on making GDB MCP easier for AI agents to use in real debugging sessions:

• Fixed execution commands returning too early. run, continue, step, next, and finish now wait until GDB reports *stopped, so breakpoint hits and crashes are returned with the same command.
• Added a top-level stopped object to execution results, including stop reason, frame, thread, and breakpoint number when GDB provides them.
• Fixed multi-line GDB command blocks. commands ... end, define ... end, python ... end, if ... end, and while ... end no longer deadlock.
• Added per-command timeout_sec for long-running debug operations.
• Added hardware breakpoint support with hardware=true.
• Added an SSH stdio bridge example for running the MCP server on a remote VM while the MCP client runs locally.

Architecture

This server uses the GDB/MI (Machine Interface) protocol, which is the same interface used by professional IDEs. It provides:

• Structured, machine-parseable output
• Full access to GDB's debugging capabilities
• Reliable command execution and response handling

Installation

Prerequisites

• Python 3.10 or higher
• GDB installed and available in PATH

Quick Start

# Install pipx if needed
python3 -m pip install --user pipx
python3 -m pipx ensurepath

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

For alternative installation methods (virtual environment, manual setup), see INSTALL.md.

Configuration

Claude Desktop

Add this to your Claude Desktop configuration file:

Location:

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

Configuration:

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

For other installation methods and MCP clients, see INSTALL.md.

opencode

Add a project-level opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gdb": {
      "type": "local",
      "command": ["gdb-mcp-server"],
      "enabled": true,
      "timeout": 20000
    }
  }
}

For remote VM debugging, run the MCP server over SSH with the bridge example:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gdb_remote": {
      "type": "local",
      "command": ["python", "examples/gdb_mcp_ssh_bridge.py"],
      "enabled": true,
      "timeout": 20000,
      "env": {
        "GDB_MCP_SSH_HOST": "your-vm-host",
        "GDB_MCP_SSH_USER": "root",
        "GDB_MCP_REMOTE_COMMAND": "cd /path/to/gdb-mcp && GDB_MCP_LOG_LEVEL=ERROR exec ./venv/bin/python -m gdb_mcp"
      }
    }
  }
}

Use SSH keys when possible. If password auth is required, set GDB_MCP_SSH_PASSWORD in your shell environment instead of committing it to opencode.json.

Start opencode from the project directory and tell the agent:

use gdb_remote

Environment Variables

The GDB MCP Server supports the following environment variables:

GDB_PATH

Specify the path to the GDB executable to use. This is useful when:

• You have multiple GDB versions installed
• GDB is installed in a non-standard location
• You want to use a custom or patched GDB build

Default: gdb (resolved via system PATH)

Example:

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

Note: The gdb_path parameter in the gdb_start_session tool overrides this environment variable if both are specified.

GDB_MCP_LOG_LEVEL

Set the logging level for the server.

Default: INFO Options: DEBUG, INFO, WARNING, ERROR, CRITICAL

Example:

export GDB_MCP_LOG_LEVEL=DEBUG
gdb-mcp-server

Available Tools

The GDB MCP Server provides 22 tools for controlling GDB debugging sessions:

Session Management:

• gdb_start_session - Start a new GDB session with optional initialization
• gdb_execute_command - Execute GDB commands (CLI or MI format)
• gdb_call_function - Call a function in the target process (dedicated tool for separate permissioning)
• gdb_get_status - Get current session status
• gdb_stop_session - Stop the current session

Thread & Frame Navigation:

• gdb_get_threads - List all threads
• gdb_select_thread - Select a specific thread
• gdb_get_backtrace - Get stack trace for a thread
• gdb_select_frame - Select a specific stack frame
• gdb_get_frame_info - Get information about the current frame

Breakpoint Management:

• gdb_set_breakpoint - Set breakpoints with optional conditions, temporary mode, or hardware mode
• gdb_list_breakpoints - List all breakpoints with structured data
• gdb_delete_breakpoint - Delete a breakpoint by number
• gdb_enable_breakpoint - Enable a breakpoint
• gdb_disable_breakpoint - Disable a breakpoint

Execution Control:

• gdb_continue - Continue execution
• gdb_step - Step into functions
• gdb_next - Step over functions
• gdb_interrupt - Pause a running program

Data Inspection:

• gdb_evaluate_expression - Evaluate expressions
• gdb_get_variables - Get local variables
• gdb_get_registers - Get CPU registers

For detailed documentation of each tool including parameters, return values, and examples, see TOOLS.md.

Usage Examples

Example 1: Analyzing a Core Dump

User: "Load the core dump at /tmp/core.12345, set the sysroot to /opt/sysroot, and tell me how many threads there were when it crashed."

AI Actions:

1. Start session with init commands:

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

2. Get threads: gdb_get_threads
3. Report: "There were 8 threads when the program crashed."

Example 2: Conditional Breakpoint Investigation

User: "Set a breakpoint at process_data but only when the count variable is greater than 100, then continue execution."

AI Actions:

1. Set conditional breakpoint:

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

2. Continue execution: gdb_continue
3. When hit, inspect state

For more detailed usage examples and workflows, see examples/USAGE_GUIDE.md and examples/README.md.

Advanced Usage

Custom GDB Initialization Scripts

Create a .gdb file with your setup commands:

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

# Set up symbol paths
set sysroot /opt/sysroot
set solib-search-path /opt/libs:/usr/local/lib

# Convenience settings
set print pretty on
set print array on
set pagination off

Then use it:

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

Python Initialization Scripts

You can also use GDB's Python API:

# init.py
import gdb
gdb.execute("file /path/to/program")
gdb.execute("core-file /path/to/core")
# Custom analysis

Use with:

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

Working with Running Processes

While this server primarily works with core dumps and executables, you can attach to running processes:

{
  "init_commands": [
    "attach 12345"  // PID of running process
  ]
}

Note: This requires appropriate permissions (usually root or same user).

Troubleshooting

Common Issues

GDB Not Found

which gdb
gdb --version

Long-running Execution

Execution commands block until the target stops, exits, crashes, or times out. For long-running programs, pass a larger timeout_sec to gdb_execute_command, gdb_continue, gdb_step, or gdb_next.

If the target is still running after the timeout, use gdb_interrupt to pause it.

Program States:

• Not started: Use gdb_execute_command with "run" or "start"
• Running: Program is executing - use gdb_interrupt to pause it
• Paused (at breakpoint): Use gdb_continue, gdb_step, gdb_next, inspect variables
• Finished: Program has exited - restart with "run" if needed

Missing Debug Symbols

Always check the warnings field in gdb_start_session response! Compile your programs with the -g flag.

For detailed troubleshooting, installation issues, and more solutions, see INSTALL.md.

How It Works

1. GDB/MI Protocol: The server communicates with GDB using the Machine Interface (MI) protocol, the same interface used by IDEs.

2. pygdbmi Library: We use the excellent pygdbmi library to handle the low-level protocol details and response parsing.

3. MCP Integration: The server exposes GDB functionality as MCP tools, allowing AI assistants to:

   • Understand the available debugging operations
   • Execute commands with proper parameters
   • Interpret structured responses

4. Session Management: A single GDB session is maintained per server instance, allowing stateful debugging across multiple tool calls.

Contributing

Contributions welcome! Areas for improvement:

• Additional GDB commands (e.g., watchpoints, memory inspection)
• Better error handling and recovery
• Enhanced output formatting

License

MIT

References

• GDB Machine Interface (MI)
• pygdbmi Documentation
• Model Context Protocol