stass/lldb-mcp

See it in acton here, automatically debugging a buffer overflow: https://x.com/full_duplex/status/1904770477698277847

Overview

LLDB-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.

The tool provides a comprehensive set of commands for working with LLDB, including:

• Starting and managing LLDB sessions
• Loading programs for debugging
• Setting breakpoints and watchpoints
• Controlling program execution
• Examining memory, registers, and variables
• Analyzing stack traces and program state

Features

• Create and manage multiple LLDB debugging sessions
• Load executables and attach to running processes
• Load core dump files for post-mortem analysis
• Execute arbitrary LLDB commands
• Fine-grained control over program execution
• Memory examination and disassembly
• Thread and stack frame inspection

Installation

1. Clone the repository:

   git clone https://github.com/stass/lldb-mcp.git
   cd lldb-mcp
   

2. Install dependencies:

   pip install mcp
   

3. Configure Claude to use the LLDB-MCP server:

   • Open the Claude desktop app configuration
   • Add the following to your MCP configuration:

   "mcpServers": {
     "lldb-mcp": {
       "command": "python3",
       "args": ["/path/to/lldb-mcp/lldb_mcp.py"],
       "disabled": false
     }
   }
   

Usage

Once installed and configured, you can interact with LLDB through Claude using natural language.

Basic Workflow

1. Start a new LLDB session
2. Load a program
3. Set breakpoints
4. Run the program
5. Inspect variables and memory
6. Control execution (continue, step, next, etc.)
7. Terminate the session when done

Example Commands

Here are some examples of how to interact with LLDB-MCP through Claude:

• "Start a new LLDB session"
• "Load the program '/path/to/executable'"
• "Set a breakpoint at main"
• "Run the program"
• "Show backtrace"
• "Print the value of variable 'count'"
• "Step over the next line"
• "Examine memory at address 0x1000"
• "Show register values"
• "Continue execution"
• "Kill the process"
• "Terminate the LLDB session"

Supported Commands

Session Management

• lldb_start: Start a new LLDB session
• lldb_terminate: Terminate an LLDB session
• lldb_list_sessions: List all active LLDB sessions

Program Loading

• lldb_load: Load a program into LLDB
• lldb_attach: Attach to a running process
• lldb_load_core: Load a core dump file

Execution Control

• lldb_run: Run the loaded program
• lldb_continue: Continue program execution
• lldb_step: Step to next line or instruction
• lldb_next: Step over function calls
• lldb_finish: Execute until the current function returns
• lldb_kill: Kill the running process

Breakpoints and Watchpoints

• lldb_set_breakpoint: Set a breakpoint
• lldb_breakpoint_list: List all breakpoints
• lldb_breakpoint_delete: Delete a breakpoint
• lldb_watchpoint: Set a watchpoint on a variable or memory address

Inspection

• lldb_backtrace: Show call stack
• lldb_print: Print value of expression
• lldb_examine: Examine memory
• lldb_info_registers: Display registers
• lldb_frame_info: Get detailed information about a stack frame
• lldb_disassemble: Disassemble code
• lldb_process_info: Get information about the current process

Thread Management

• lldb_thread_list: List all threads in the current process
• lldb_thread_select: Select a specific thread

Miscellaneous

• lldb_command: Execute an arbitrary LLDB command
• lldb_expression: Evaluate an expression in the current frame
• lldb_help: Get help for LLDB commands

Example program

example/overflow.c contains an example C program that causes buffer overflow with certain arguments. Compile it using cc overflow.c and ask Claude to debug the issue with the resulting program:

I'm trying to debug my program a.out that is crashing with certain arguments, e.g. when I pass "hello".
Can you help me debug it?

Debugging Tips

• Use lldb_command when you need to execute LLDB commands that don't have a dedicated function
• Enable debug mode with --debug flag when starting the server for detailed logging
• Sessions are automatically cleaned up when the server shuts down
• Each session has a unique ID - make sure to use the correct ID when executing commands

Requirements

• Python 3.7+
• LLDB installed on the system
• Claude desktop app with MCP support

Troubleshooting

• If LLDB commands are timing out, check that LLDB is installed correctly
• Verify the path to LLDB when starting a new session
• Check for permission issues when attaching to processes
• Review debug logs if commands aren't executing correctly

License

BSD 2-clause