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:

MCP Server (server.py) - Handles client connections and request routing
GDB Manager (gdb_manager.py) - Manages GDB subprocess lifecycle
Session Management - Maintains isolated debugging sessions with automatic timeout
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)

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

An MCP server that provides programmatic access to the GNU Debugger (GDB), enabling AI models to interact with GDB through natural language for debugging tasks.

Related MCP Servers

MCP Server GDB
pansila
-
security
A
license
-
quality
A GDB/MI protocol server based on the MCP protocol, providing remote application debugging capabilities.
Last updated -
39
Rust
MIT License
LLDB-MCP
stass
-
security
A
license
-
quality
A MCP server for LLDB that allows automatic analyzing, debugging and disassembling of native apps.
Last updated -
51
Python
BSD 2-Clause "Simplified" License
Cloud Monitoring API Server
ag2-mcp-servers
-
security
F
license
-
quality
An MCP server that provides access to Google Cloud Monitoring API, enabling interaction with cloud resources monitoring data through natural language commands.
Last updated -
Python
Policy Troubleshooter API MCP Server
ag2-mcp-servers
-
security
F
license
-
quality
An MCP server that provides natural language interaction with Google's Policy Troubleshooter API, allowing users to troubleshoot access denied errors and analyze IAM policies.
Last updated -
Python

View all related MCP servers