Multi-Debugger MCP Server (LLDB and GDB)

A Model Context Protocol server that provides debugging functionality for both GDB and LLDB debuggers, for use with Claude Desktop, VSCode Copilot, or other AI assistants.

Quick Start

uv sync
uv venv
uv run server.py

Integration

Note that you can use uv run to run the server.py script or you can use uv venv to create a virtual environment and then run /home/youruser/dev/personal/GDB-MCP/.venv/bin/python /home/youruser/dev/personal/GDB-MCP/server.py.

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "gdb": {
      "command": "uv",
      "args": ["run", "/home/youruser/dev/personal/GDB-MCP/server.py"],
      "disabled": false
    }
  }
}

VSCode Copilot

If you're using WSL:

 "mcp": {
    "servers": {
      "my-mcp-server-4dc36648": {
        "type": "stdio",
        "command": "wsl",
        "args": [
          "/home/youruser/dev/personal/GDB-MCP/.venv/bin/python",
          "/home/youruser/dev/personal/GDB-MCP/server.py"
        ]
      }
    }
  }

If you're not using WSL:

  "mcp": {
    "servers": {
      "my-mcp-server-db89eee1": {
        "type": "stdio",
        "command": "/home/youruser/dev/personal/GDB-MCP/.venv/bin/python",
        "args": ["/home/youruser/dev/personal/GDB-MCP/server.py"]
      }
    }
  }

Windsurf

{
  "mcpServers": {
    "debugger-mcp": {
      "command": "python3",
      "args": ["/Users/youruser/dev/GDB-MCP/server.py"]
    }
  }
}

Experimental LLDB Support (macOS)

This project includes experimental native LLDB support alongside GDB, with automatic debugger selection.

Installation

To enable LLDB support on macOS, install LLVM (which includes LLDB) and python via Homebrew:

# Install LLDB for supporting python3.14 bindings
brew install llvm python3

# Install MCP and debugging dependencies
pip3 install mcp pygdbmi --break-system-packages

Available Tools

Unified Tools

debugger_status(): Show available debuggers and their status
debugger_start(): Start debugging session with auto-detected debugger
debugger_terminate(session_id): Terminate debugging session
debugger_list_sessions(): List all active debugging sessions
debugger_command(session_id, command): Execute debugger command

LLDB Tools

lldb_start(): Start new LLDB debugging session
lldb_terminate(session_id): Terminate LLDB debugging session
lldb_list_sessions(): List all active LLDB sessions
lldb_command(session_id, command): Execute arbitrary LLDB command

GDB Tools

gdb_start(gdb_path): Start new GDB debugging session
gdb_terminate(session_id): Terminate GDB debugging session
gdb_list_sessions(): List all active GDB sessions
gdb_command(session_id, command): Execute any GDB command

Use *_command() functions for all advanced debugger operations, your LLM client should already know how to use it, but it doesn't hurt to mention it.

Checking Status

You can verify debugger availability:

from modules.lldb import LLDBSessionManager
from modules.gdb import GDBSessionManager

print("LLDB available:", LLDBSessionManager.is_available())
print("GDB available:", GDBSessionManager.is_available())

Testing

uv run python run-tests.py --check-deps
uv run python run-tests.py --type all

Examples

Check the examples directory for example prompts.

Example binaries are compiled to arm64 and amd64, pick the one that matches your system architecture.

License

This project is licensed under the GNU Version 3.0 License, see the LICENSE file for details.

Multi-Debugger MCP Server (LLDB and GDB)