LLDB MCP server

LLDB-MCP is a powerful tool that integrates the LLDB debugger with Claude's Model Context Protocol (MCP), enabling AI-assisted debugging workflows. This integration allows Claude to directly control and interact with LLDB debugging sessions, providing a comprehensive set of commands for debugging programs through natural language interaction.

Installation

Clone the Repository

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

Install Dependencies

pip install mcp

Configure Claude

Open the Claude desktop app configuration and add the following to your MCP configuration:

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

Basic Usage

Workflow Overview

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 Interactions

You can interact with LLDB-MCP through Claude using natural language commands such as:

• "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"

Command Reference

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

Practical Example

To debug a buffer overflow issue in a program:

1. Start a session: "Start a new LLDB session"

2. Load the program: "Load the program './a.out'"

3. Set a breakpoint at the main function: "Set a breakpoint at main"

4. Run the program with arguments: "Run the program with arguments 'hello'"

5. Step through the code to identify the issue: "Step over the next line" "Print the value of variable 'buffer'"

6. Examine memory before the crash: "Examine memory near buffer"

7. When the program crashes, check the stack trace: "Show backtrace"

Troubleshooting

• If LLDB commands time out, verify that LLDB is installed correctly on your system
• Check that the path to the LLDB executable is correct when starting a new session
• If you encounter permission issues when attaching to processes, you may need to run with elevated privileges
• Use the --debug flag when starting the server for detailed logging information
• Ensure you're using the correct session ID when executing commands across multiple sessions

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.