mcp-lldb

An MCP server that exposes LLDB debugging to AI agents via the Model Context Protocol. Zero external Python dependencies — the MCP protocol is implemented directly.

Requirements

• macOS with Xcode installed (not just Command Line Tools)
• The lldb command must be on your PATH (xcode-select --install if needed)

The launch script automatically discovers which Python version ships with your copy of Xcode and uses it — no manual version management required.

Setup

1. Make the launcher executable

chmod +x /Users/jcroix/programs/mcp-lldb/launch.sh

2. Add to Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "lldb": {
      "command": "/Users/jcroix/programs/mcp-lldb/launch.sh"
    }
  }
}

Restart Claude Desktop. The server appears in the MCP tools panel.

3. Verify connectivity (optional)

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1"}}}' \
  | /Users/jcroix/programs/mcp-lldb/launch.sh

You should see a JSON response with "protocolVersion":"2024-11-05".

Available tools (31 total)

Group	Tools
Lifecycle	launch_process, attach_process, detach_process, kill_process
Execution	continue_process, stop_process, step_over, step_into, step_out, step_instruction
Breakpoints	set_breakpoint, delete_breakpoint, enable_breakpoint, disable_breakpoint, list_breakpoints
Watchpoints	set_watchpoint, delete_watchpoint, list_watchpoints
Threads/Frames	list_threads, select_thread, backtrace, select_frame
Variables	get_locals, read_variable, evaluate_expression
Memory	read_memory, write_memory
Registers	get_registers
Modules	list_modules, find_symbol, disassemble, get_source_context
State	get_state, read_process_output
Escape hatch	run_lldb_command

Usage example

Ask Claude (in Claude Desktop with the server connected):

Launch /usr/bin/ls with args ["/tmp"], set a breakpoint on main, continue, show me the backtrace and local variables.

Recommended workflow

Always launch with stop_at_entry: true (the default), set your breakpoints, then call continue_process. If you launch with stop_at_entry: false and no breakpoints are set, the process runs to completion before the first tool call returns.

launch_process(program=..., stop_at_entry=true)   # stops at _dyld_start
set_breakpoint(name="main")                        # or file+line
continue_process()                                 # runs until breakpoint hit
get_locals() / backtrace() / evaluate_expression() # inspect

Notes

• User binaries only: macOS System Integrity Protection (SIP) prevents attaching to system binaries (/bin/*, /usr/bin/*, etc.). Debug your own compiled programs; build with -g -O0 for best results.
• Process I/O isolation: Launched processes have their stdin/stdout/stderr redirected to temp files so they don't corrupt the MCP JSON stream. Use read_process_output to read what the program printed.
• Synchronous mode: All step and continue operations block until the process reaches the next stop event, so each tool call completes atomically.
• run_lldb_command: The escape hatch for anything not covered by the named tools — accepts any LLDB command string and returns its output.