# 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.
<p align="center">
<img src="images/gdb-mcp.png" alt="GDB MCP Server" width="600">
</p>
## Quick Start
```bash
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`:
```json
{
"mcpServers": {
"gdb": {
"command": "uv",
"args": ["run", "/home/youruser/dev/personal/GDB-MCP/server.py"],
"disabled": false
}
}
}
```
### VSCode Copilot
If you're using WSL:
```json
"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:
```json
"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
```json
{
"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.
<p align="center">
<img src="images/multi-debugger.png" alt="Multi-Debugger MCP Server" width="600">
</p>
### Installation
To enable LLDB support on macOS, install LLVM (which includes LLDB) and python via Homebrew:
```bash
# 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:
```python
from modules.lldb import LLDBSessionManager
from modules.gdb import GDBSessionManager
print("LLDB available:", LLDBSessionManager.is_available())
print("GDB available:", GDBSessionManager.is_available())
```
## Testing
```bash
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.
