hnmr293/gdb-mcp

GDB-MCP

https://github.com/user-attachments/assets/84e717ba-6983-442d-bf11-7ba2b17108af

GDB-MCP is a Model Context Protocol (MCP) server that provides programmatic access to the GNU Debugger (GDB). It enables AI models and other MCP clients to interact with GDB through a standardized interface, making debugging capabilities accessible through natural language interactions.

Since it uses the gdb/mi interface, you can access the full functionality of gdb. We also provide a command reference for gdb in resources.

Features

• Session Management: Create and manage multiple isolated GDB debugging sessions
• Command Execution: Execute both CLI and MI (Machine Interface) GDB commands
• Comprehensive Documentation: Access complete GDB command reference through MCP resources
• Asynchronous Operation: Built on asyncio for efficient concurrent session handling
• Timeout Protection: Automatic cleanup of idle sessions to prevent resource leaks

Installation

Prerequisites

• Python 3.12 or higher
• GDB installed on your system
• MCP-compatible client (e.g., Claude Desktop)

Install from Source

# Clone the repository
git clone https://github.com/yourusername/gdb-mcp.git
cd gdb-mcp

# Install dependencies
pip install -r requirements.txt

# Install the package
pip install -e .

Quick Start

Running the Server

# Start the MCP server
gdb-mcp

# Or run directly with Python
python -m gdb_mcp

Claude Desktop Configuration

Add the following to your Claude Desktop configuration file:

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

See examples/claude_code_config_example.json for a complete configuration example.

Usage

Available Resources

The server provides comprehensive GDB documentation through MCP resources:

• gdb://commands/reference - Complete GDB command reference
• gdb://commands/cli - CLI commands with abbreviations
• gdb://commands/mi - Machine Interface commands
• gdb://commands/mapping - CLI to MI command correspondence

Available Tools

open - Start a debugging session

{
  "name": "open",
  "arguments": {
    "timeout": 300  // Optional, defaults to 300 seconds
  }
}

call - Execute a GDB command

{
  "name": "call",
  "arguments": {
    "id": "session-uuid",
    "command": "break main"
  }
}

close - Close a debugging session

{
  "name": "close",
  "arguments": {
    "id": "session-uuid"
  }
}

list_sessions - List all active sessions

{
  "name": "list_sessions",
  "arguments": {}
}

Example Usage

Basic Debugging Session

# Start a new debugging session
session = await client.call_tool("open", {})
session_id = session["content"]["id"]

# Load an executable
await client.call_tool("call", {
    "id": session_id,
    "command": "file /path/to/program"
})

# Set a breakpoint
await client.call_tool("call", {
    "id": session_id,
    "command": "break main"
})

# Run the program
result = await client.call_tool("call", {
    "id": session_id,
    "command": "run"
})

# Examine variables
result = await client.call_tool("call", {
    "id": session_id,
    "command": "print variable_name"
})

# Close the session
await client.call_tool("close", {"id": session_id})

Accessing Documentation

# Get CLI commands reference
cli_docs = await client.read_resource("gdb://commands/cli")

# Get MI commands reference
mi_docs = await client.read_resource("gdb://commands/mi")

Architecture

GDB-MCP consists of several key components:

1. MCP Server (server.py) - Handles client connections and request routing
2. GDB Manager (gdb_manager.py) - Manages GDB subprocess lifecycle
3. Session Management - Maintains isolated debugging sessions with automatic timeout
4. Resource Provider - Serves comprehensive GDB documentation

The server operates GDB in MI (Machine Interface) mode internally for reliable command parsing and structured output.

Development

Project Structure

gdb-mcp/
    src/gdb_mcp/
        __init__.py
        __main__.py
        cli.py              # CLI entry point
        server.py           # MCP server implementation
        gdb_manager.py      # GDB process management
    resources/
        gdb_commands.md     # GDB command reference
    docs/                   # Additional documentation
    examples/               # Usage examples
    tests/                  # Test suite
    scripts/                # Utility scripts

Security Considerations

• Designed for local debugging only
• Each GDB session runs in an isolated process
• Automatic session timeout prevents resource leaks
• File system access limited to user permissions

Acknowledgments

• Built on the Model Context Protocol
• Powered by GNU Debugger (GDB)