中文文档 | 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:

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

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:

{
  "servers": {
    "mcp-lldb": {
      "type": "stdio",
      "command": "/path/to/mcp-lldb",
      "args": []
    }
  }
}

Claude Desktop / Cline / Other MCP Clients

{
  "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:

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 — MCP server for Linux GDB debugging
• Model Context Protocol
• LLDB Documentation

License

AGPL-3.0-or-later