Skip to content

Commit 1eb8c46

Browse files
FlorentinoJinkFlorentinoJink
committed
feat: initial mcp-gdb implementation with core dump, remote debug, and launch debug support
0 parents  commit 1eb8c46

15 files changed

Lines changed: 2992 additions & 0 deletions

File tree

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
/target
2+
/mcp-windbg
3+
/test_app/test_app
4+
Cargo.lock
5+
.kiro/

‎Cargo.toml‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
[package]
2+
name = "mcp-gdb"
3+
version = "0.1.0"
4+
edition = "2021"
5+
authors = ["MCP GDB Contributors"]
6+
description = "A high-performance Model Context Protocol server for Linux GDB debugging"
7+
license = "AGPL-3.0-or-later"
8+
9+
[[bin]]
10+
name = "mcp-gdb"
11+
path = "src/main.rs"
12+
13+
[dependencies]
14+
tokio = { version = "1.40", features = ["full"] }
15+
serde = { version = "1.0", features = ["derive"] }
16+
serde_json = "1.0"
17+
thiserror = "2.0"
18+
anyhow = "1.0"
19+
tracing = "0.1"
20+
tracing-subscriber = { version = "0.3", features = ["env-filter"] }
21+
clap = { version = "4.5", features = ["derive"] }
22+
rmcp = { version = "0.8.5", features = ["transport-io", "server"] }
23+
24+
[dev-dependencies]
25+
proptest = "1.4"
26+
tempfile = "3.8"
27+
tokio-test = "0.4"

‎LICENSE‎

Lines changed: 661 additions & 0 deletions
Large diffs are not rendered by default.

‎README.md‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
# mcp-gdb
2+
3+
[中文文档](README_CN.md) | English
4+
5+
A [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server for GDB — core dump analysis, remote debugging, and direct program debugging on Linux.
6+
7+
Built with Rust and [Tokio](https://tokio.rs/) for async I/O. Ships as a single executable with no runtime dependencies.
8+
9+
## Features
10+
11+
- **Core dump analysis** — Open core files, inspect threads, stack traces, and shared libraries
12+
- **Remote debugging** — Connect to gdbserver targets via `host:port`
13+
- **Direct program debugging** — Launch executables under GDB, set breakpoints, step through code, inspect variables
14+
- **Session management** — Multiple concurrent debug sessions with automatic reuse
15+
- **Configurable timeouts** — Separate timeouts for initialization (symbol loading) and command execution
16+
- **Debuginfod control** — Option to disable automatic symbol downloading for restricted networks
17+
- **Stripped binary support** — Configure `debug_info_directory` and `sysroot` for separated debug info
18+
19+
## Prerequisites
20+
21+
- Linux
22+
- GDB
23+
24+
If GDB is not installed:
25+
26+
```bash
27+
# Debian/Ubuntu
28+
sudo apt install gdb
29+
30+
# RHEL/CentOS/Fedora
31+
sudo dnf install gdb
32+
33+
# Arch
34+
sudo pacman -S gdb
35+
```
36+
37+
The server auto-discovers GDB from `PATH` and common Linux paths (`/usr/bin/gdb`, `/usr/local/bin/gdb`).
38+
39+
## Installation
40+
41+
### From source
42+
43+
```bash
44+
git clone https://github.com/FlorentinoJink/mcp-gdb.git
45+
cd mcp-gdb
46+
cargo build --release
47+
```
48+
49+
Binary: `target/release/mcp-gdb`
50+
51+
## Configuration
52+
53+
### VS Code / Kiro
54+
55+
`.vscode/mcp.json`:
56+
57+
```json
58+
{
59+
"servers": {
60+
"mcp-gdb": {
61+
"type": "stdio",
62+
"command": "/path/to/mcp-gdb",
63+
"args": []
64+
}
65+
}
66+
}
67+
```
68+
69+
### Claude Desktop / Cline / Other MCP Clients
70+
71+
```json
72+
{
73+
"mcpServers": {
74+
"mcp-gdb": {
75+
"command": "mcp-gdb",
76+
"args": []
77+
}
78+
}
79+
}
80+
```
81+
82+
### Environment Variables
83+
84+
| Variable | Description | Default |
85+
|----------|-------------|---------|
86+
| `GDB_PATH` | Custom path to GDB executable | Auto-discovered |
87+
| `MCP_GDB_TIMEOUT` | Command execution timeout (seconds) | `30` |
88+
| `MCP_GDB_INIT_TIMEOUT` | Initialization timeout for symbol loading (seconds) | `120` |
89+
| `MCP_GDB_VERBOSE` | Verbose logging (`true`/`false`) | `false` |
90+
| `MCP_GDB_DISABLE_DEBUGINFOD` | Disable debuginfod automatic symbol downloading (`true`/`false`) | `false` |
91+
92+
### CLI Options
93+
94+
```
95+
mcp-gdb [OPTIONS]
96+
97+
--timeout <SECONDS> Command execution timeout (default: 30)
98+
--init-timeout <SECONDS> Initialization timeout (default: 120)
99+
--verbose Enable verbose logging
100+
--disable-debuginfod Disable debuginfod automatic symbol downloading
101+
```
102+
103+
## Tools
104+
105+
| Tool | Description |
106+
|------|-------------|
107+
| `open_gdb_core` | Open and analyze a Linux core dump file |
108+
| `open_gdb_remote` | Connect to a gdbserver remote debugging target |
109+
| `launch_debug` | Launch a program under GDB for debugging |
110+
| `run_gdb_cmd` | Execute a GDB command in an existing session |
111+
| `close_gdb_core` | Close a core dump analysis session |
112+
| `close_gdb_remote` | Close a remote debugging session |
113+
| `close_debug` | Close a launch debug session and terminate the program |
114+
| `list_core_dumps` | List core dump files in a directory |
115+
116+
## Usage Examples
117+
118+
### Core Dump Analysis
119+
120+
```
121+
Analyze the core dump at /tmp/core.12345
122+
```
123+
124+
### Remote Debugging
125+
126+
```
127+
Connect to gdbserver at 192.168.1.100:1234 and show the current state
128+
```
129+
130+
### Direct Program Debugging
131+
132+
Launch a program, set breakpoints, step through code:
133+
134+
```
135+
Launch /home/user/myapp for debugging
136+
```
137+
138+
Then use `run_gdb_cmd` to control execution:
139+
140+
```
141+
break main — Set breakpoint at main
142+
run — Start execution
143+
next — Step over
144+
step — Step into
145+
bt — Backtrace
146+
info locals — View local variables
147+
list — Show source at current location
148+
continue — Continue execution
149+
```
150+
151+
The `launch_debug` tool supports optional parameters:
152+
153+
| Parameter | Type | Description |
154+
|-----------|------|-------------|
155+
| `program_path` | string | Path to the executable to debug (required) |
156+
| `arguments` | string[] | Command line arguments |
157+
| `working_directory` | string | Working directory |
158+
| `debug_info_directory` | string | Path to separated debug info (for stripped binaries) |
159+
| `source_path` | string | Source file search path |
160+
| `include_backtrace` | boolean | Include initial backtrace |
161+
| `include_modules` | boolean | Include shared library list |
162+
163+
The `open_gdb_core` tool supports optional parameters:
164+
165+
| Parameter | Type | Description |
166+
|-----------|------|-------------|
167+
| `core_dump_path` | string | Path to the core dump file (required) |
168+
| `executable_path` | string | Path to the executable (for symbol loading) |
169+
| `include_backtrace` | boolean | Include backtrace output |
170+
| `include_threads` | boolean | Include thread list |
171+
| `include_shared_libraries` | boolean | Include shared library list |
172+
| `debug_info_directory` | string | Path to separated debug info directory |
173+
| `sysroot` | string | Sysroot path for cross-debugging |
174+
175+
### Close a Session
176+
177+
```
178+
Close the debug session for /home/user/myapp
179+
```
180+
181+
## Troubleshooting
182+
183+
**GDB not found** — Install via your package manager (`apt install gdb`, `dnf install gdb`) or set `GDB_PATH` to your GDB location.
184+
185+
**Symbol downloading blocks GDB** — Use `--disable-debuginfod` or set `MCP_GDB_DISABLE_DEBUGINFOD=true` to prevent GDB from downloading symbols over the network.
186+
187+
**Command timeout** — Increase with `--timeout 60` or `MCP_GDB_TIMEOUT=60`. Large core dumps and symbol loading may need higher `MCP_GDB_INIT_TIMEOUT`.
188+
189+
**ptrace errors in containers** — If running in Docker/containers, add `--cap-add=SYS_PTRACE` to your `docker run` command. For VMs like OrbStack, ptrace may have limited support.
190+
191+
**Stripped binaries** — Use the `debug_info_directory` parameter to point to separated debug info (typically `/usr/lib/debug/`). Install debug symbol packages: `apt install <package>-dbg` or `dnf debuginfo-install <package>`.
192+
193+
## Related
194+
195+
- [mcp-windbg](https://github.com/FlorentinoJink/mcp-windbg) — MCP server for Windows debugging (WinDbg/CDB)
196+
- [Model Context Protocol](https://modelcontextprotocol.io/)
197+
- [GDB Documentation](https://sourceware.org/gdb/current/onlinedocs/gdb/)
198+
199+
## License
200+
201+
[AGPL-3.0-or-later](./LICENSE)

0 commit comments

Comments
 (0)