Lldb MCP

1# LLDB-MCP
2 
3![Screenshot](screenshot.png)
4 
5See it in acton here, automatically debugging a buffer overflow: https://x.com/full_duplex/status/1904770477698277847
6 
7## Overview
8 
9LLDB-MCP is a tool that integrates the LLDB debugger with Claude's Model Context Protocol (MCP). This integration allows Claude to start, control, and interact with LLDB debugging sessions directly, enabling AI-assisted debugging workflows.
10 
11The tool provides a comprehensive set of commands for working with LLDB, including:
12- Starting and managing LLDB sessions
13- Loading programs for debugging
14- Setting breakpoints and watchpoints
15- Controlling program execution
16- Examining memory, registers, and variables
17- Analyzing stack traces and program state
18 
19## Features
20 
21- Create and manage multiple LLDB debugging sessions
22- Load executables and attach to running processes
23- Load core dump files for post-mortem analysis
24- Execute arbitrary LLDB commands
25- Fine-grained control over program execution
26- Memory examination and disassembly
27- Thread and stack frame inspection
28 
29## Installation
30 
311. Clone the repository:
32   ```
33   git clone https://github.com/stass/lldb-mcp.git
34   cd lldb-mcp
35   ```
36 
372. Install dependencies:
38   ```
39   pip install mcp
40   ```
41 
423. Configure Claude to use the LLDB-MCP server:
43   - Open the Claude desktop app configuration
44   - Add the following to your MCP configuration:
45   ```json
46   "mcpServers": {
47     "lldb-mcp": {
48       "command": "python3",
49       "args": ["/path/to/lldb-mcp/lldb_mcp.py"],
50       "disabled": false
51     }
52   }
53   ```
54 
55## Usage
56 
57Once installed and configured, you can interact with LLDB through Claude using natural language.
58 
59### Basic Workflow
60 
611. Start a new LLDB session
622. Load a program
633. Set breakpoints
644. Run the program
655. Inspect variables and memory
666. Control execution (continue, step, next, etc.)
677. Terminate the session when done
68 
69### Example Commands
70 
71Here are some examples of how to interact with LLDB-MCP through Claude:
72 
73- "Start a new LLDB session"
74- "Load the program '/path/to/executable'"
75- "Set a breakpoint at main"
76- "Run the program"
77- "Show backtrace"
78- "Print the value of variable 'count'"
79- "Step over the next line"
80- "Examine memory at address 0x1000"
81- "Show register values"
82- "Continue execution"
83- "Kill the process"
84- "Terminate the LLDB session"
85 
86## Supported Commands
87 
88### Session Management
89- `lldb_start`: Start a new LLDB session
90- `lldb_terminate`: Terminate an LLDB session
91- `lldb_list_sessions`: List all active LLDB sessions
92 
93### Program Loading
94- `lldb_load`: Load a program into LLDB
95- `lldb_attach`: Attach to a running process
96- `lldb_load_core`: Load a core dump file
97 
98### Execution Control
99- `lldb_run`: Run the loaded program
100- `lldb_continue`: Continue program execution
101- `lldb_step`: Step to next line or instruction
102- `lldb_next`: Step over function calls
103- `lldb_finish`: Execute until the current function returns
104- `lldb_kill`: Kill the running process
105 
106### Breakpoints and Watchpoints
107- `lldb_set_breakpoint`: Set a breakpoint
108- `lldb_breakpoint_list`: List all breakpoints
109- `lldb_breakpoint_delete`: Delete a breakpoint
110- `lldb_watchpoint`: Set a watchpoint on a variable or memory address
111 
112### Inspection
113- `lldb_backtrace`: Show call stack
114- `lldb_print`: Print value of expression
115- `lldb_examine`: Examine memory
116- `lldb_info_registers`: Display registers
117- `lldb_frame_info`: Get detailed information about a stack frame
118- `lldb_disassemble`: Disassemble code
119- `lldb_process_info`: Get information about the current process
120 
121### Thread Management
122- `lldb_thread_list`: List all threads in the current process
123- `lldb_thread_select`: Select a specific thread
124 
125### Miscellaneous
126- `lldb_command`: Execute an arbitrary LLDB command
127- `lldb_expression`: Evaluate an expression in the current frame
128- `lldb_help`: Get help for LLDB commands
129 
130## Example program
131 
132`example/overflow.c` contains an example C program that causes buffer overflow with certain arguments.
133Compile it using `cc overflow.c` and ask Claude to debug the issue with the resulting program:
134```
135I'm trying to debug my program a.out that is crashing with certain arguments, e.g. when I pass "hello".
136Can you help me debug it?
137```
138 
139## Debugging Tips
140 
141- Use `lldb_command` when you need to execute LLDB commands that don't have a dedicated function
142- Enable debug mode with `--debug` flag when starting the server for detailed logging
143- Sessions are automatically cleaned up when the server shuts down
144- Each session has a unique ID - make sure to use the correct ID when executing commands
145 
146## Requirements
147 
148- Python 3.7+
149- LLDB installed on the system
150- Claude desktop app with MCP support
151 
152## Troubleshooting
153 
154- If LLDB commands are timing out, check that LLDB is installed correctly
155- Verify the path to LLDB when starting a new session
156- Check for permission issues when attaching to processes
157- Review debug logs if commands aren't executing correctly
158 
159## License
160 
161BSD 2-clause
162