Content
[中文文档](README_CN.md) | English
# mcp-lldb
A Model Context Protocol (MCP) server for LLDB — core dump analysis, remote debugging, and program debugging on macOS.
Built with Rust and Tokio for async I/O. Ships as a single executable with no runtime dependencies.
## Features
- **Core dump analysis** — Open core files, inspect threads, stack traces, and shared libraries
- **Remote debugging** — Connect to `debugserver` targets via `host:port`
- **Direct program debugging** — Launch executables under LLDB, set breakpoints, step through code, inspect variables
- **Session management** — Multiple concurrent debug sessions with automatic reuse and dead session eviction
- **macOS platform support** — DevToolsSecurity detection, SIP path awareness, Universal Binary architecture selection, dSYM symbol loading
- **Crash file search** — Locate `.ips`, `.crash`, and core dump files from macOS system paths
## Prerequisites
- macOS
- LLDB (comes with Xcode Command Line Tools)
If LLDB is not installed:
```bash
xcode-select --install
```
The server auto-discovers LLDB from `PATH` and common macOS paths:
- `/usr/bin/lldb`
- `/usr/local/bin/lldb`
- `/Applications/Xcode.app/Contents/Developer/usr/bin/lldb`
- `/Library/Developer/CommandLineTools/usr/bin/lldb`
## Installation
### From source
```bash
git clone https://github.com/FlorentinoJink/mcp-lldb.git
cd mcp-lldb
cargo build --release
```
Binary: `target/release/mcp-lldb`
## Configuration
### VS Code / Kiro
`.vscode/mcp.json`:
```json
{
"servers": {
"mcp-lldb": {
"type": "stdio",
"command": "/path/to/mcp-lldb",
"args": []
}
}
}
```
### Claude Desktop / Cline / Other MCP Clients
```json
{
"mcpServers": {
"mcp-lldb": {
"command": "/path/to/mcp-lldb",
"args": []
}
}
}
```
## Environment Variables
| Variable | Description | Default |
|---|---|---|
| `LLDB_PATH` | Custom path to LLDB executable | Auto-discovered |
| `MCP_LLDB_TIMEOUT` | Command execution timeout (seconds) | 30 |
| `MCP_LLDB_INIT_TIMEOUT` | Initialization timeout for symbol loading (seconds) | 120 |
| `MCP_LLDB_VERBOSE` | Verbose logging (`true`/`false`) | false |
## CLI Options
```
mcp-lldb [OPTIONS]
--timeout <SECONDS> Command execution timeout (default: 30)
--init-timeout <SECONDS> Initialization timeout (default: 120)
--verbose Enable verbose logging
```
## Tools
| Tool | Description |
|---|---|
| `open_lldb_core` | Open and analyze a macOS core dump file |
| `open_lldb_remote` | Connect to a debugserver remote debugging target |
| `launch_debug` | Launch a program under LLDB for debugging |
| `run_lldb_cmd` | Execute an LLDB command in an existing session |
| `close_lldb_core` | Close a core dump analysis session |
| `close_lldb_remote` | Close a remote debugging session |
| `close_debug` | Close a launch debug session and terminate the program |
| `list_crash_files` | List core dump and crash report files on macOS |
## Usage Examples
### Core Dump Analysis
```
Analyze the core dump at /cores/core.12345
```
### Remote Debugging
Start `debugserver` on the remote side:
```bash
debugserver 0.0.0.0:1234 /path/to/executable
```
Then connect:
```
Connect to debugserver at 192.168.1.100:1234 and show the current state
```
### Direct Program Debugging
```
Launch /usr/local/bin/myapp for debugging
```
Then use `run_lldb_cmd` to control execution:
```
breakpoint set --file main.cc --line 42 — Set breakpoint
run — Start execution
next — Step over
step — Step into
thread backtrace all — Full backtrace
frame variable — View local variables
image list — Show loaded modules
continue — Continue execution
```
### Universal Binary
```
Launch /path/to/app for debugging with architecture arm64
```
## Troubleshooting
**LLDB not found** — Install via `xcode-select --install` or set `LLDB_PATH` to your LLDB location.
**DevToolsSecurity not enabled** — Run `sudo DevToolsSecurity -enable` to allow debugging.
**SIP-protected paths** — System processes under `/usr/bin/`, `/System/`, etc. cannot be debugged while SIP is enabled.
**Hardened Runtime** — Apps with Hardened Runtime require the `com.apple.security.get-task-allow` entitlement, or remove the signature with `codesign --remove-signature <path>`.
**Core dumps not generated** — macOS disables core dumps by default. Enable with `ulimit -c unlimited`. Note: SIP may prevent writing to `/cores/`.
**Command timeout** — Increase with `--timeout 60` or `MCP_LLDB_TIMEOUT=60`.
## Related
- [mcp-gdb](https://github.com/FlorentinoJink/mcp-gdb) — MCP server for Linux GDB debugging
- [Model Context Protocol](https://modelcontextprotocol.io)
- [LLDB Documentation](https://lldb.llvm.org)
## License
AGPL-3.0-or-later
