lldb-mcp

What is LLDB-MCP?

LLDB-MCP is a tool that bridges the LLDB debugger with Claude's Model Context Protocol (MCP). This integration allows Claude, an AI, to directly initiate, manage, and interact with LLDB debugging sessions. It essentially enables AI-driven debugging, making the debugging process more intuitive and efficient through natural language commands.

How to use LLDB-MCP?

To use LLDB-MCP, you first need to clone the repository and install the mcp dependency using pip. After installation, you configure the Claude desktop app by adding LLDB-MCP as an MCP server in its configuration, specifying the Python command and the path to the lldb_mcp.py script. Once configured, you can interact with LLDB through Claude using natural language commands. A typical workflow involves starting an LLDB session, loading a program, setting breakpoints, running the program, inspecting variables and memory, controlling execution, and finally terminating the session.

Key Features of LLDB-MCP

Session Management: Create, manage, and terminate multiple LLDB debugging sessions.
Program Loading: Load executables, attach to running processes, and load core dump files for post-mortem analysis.
Execution Control: Fine-grained control over program execution, including running, continuing, stepping (step, next, finish), and killing processes.
Breakpoints and Watchpoints: Set, list, and delete breakpoints, and set watchpoints on variables or memory addresses.
Inspection: Examine memory, registers, variables, stack traces, and disassemble code. Get detailed information about stack frames and processes.
Thread Management: List and select specific threads within the current process.
Miscellaneous: Execute arbitrary LLDB commands, evaluate expressions, and access help for LLDB commands.

Use Cases of LLDB-MCP

LLDB-MCP is ideal for developers looking to streamline their debugging process with AI assistance. Specific use cases include:

Automated Debugging: Automatically debug issues like buffer overflows by integrating with Claude's AI capabilities.
Natural Language Debugging: Control LLDB sessions using natural language commands, making debugging more accessible and less reliant on memorizing complex LLDB commands.
Efficient Bug Resolution: Quickly identify and resolve bugs by leveraging AI to analyze program state and suggest debugging actions.
Post-Mortem Analysis: Load and analyze core dump files with AI assistance for efficient post-mortem debugging.
Educational Tool: A great tool for learning LLDB by interacting with it through natural language, making the learning curve smoother.

FAQ about LLDB-MCP

Q: What are the requirements for running LLDB-MCP? A: You need Python 3.7+, LLDB installed on your system, and the Claude desktop app with MCP support.

Q: What if LLDB commands are timing out? A: Check if LLDB is installed correctly, verify the path to LLDB when starting a new session, and check for permission issues if attaching to processes. Review debug logs for more detailed information.

Q: How can I execute LLDB commands that don't have a dedicated function in LLDB-MCP? A: You can use the lldb_command function to execute any arbitrary LLDB command.

Q: Are sessions automatically cleaned up? A: Yes, sessions are automatically cleaned up when the server shuts down.

Q: How do I enable debug mode? A: Start the server with the --debug flag for detailed logging.

Screenshot

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

Clone the repository:

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

Install dependencies:
```
pip install mcp
```

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

Start a new LLDB session
Load a program
Set breakpoints
Run the program
Inspect variables and memory
Control execution (continue, step, next, etc.)
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