LLDB MCP server

LLDB-MCP is a tool that integrates the LLDB debugger with Claude's Model Context Protocol (MCP), allowing Claude to control LLDB debugging sessions directly. This integration enables AI-assisted debugging workflows where Claude can manipulate debugger functions and analyze program behavior through natural language interactions.

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

Basic Workflow

Once installed and configured, you can interact with LLDB through Claude using natural language commands following this general 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 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

Debugging Example

There's an example C program that causes buffer overflow you can use to test the integration:

1. Compile the example program:

   cc overflow.c
   

2. Ask Claude to debug the issue:

   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?
   

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

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

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

See the official Claude Code MCP documentation for more details.

For 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 > Tools & Integrations and click "New MCP Server".

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

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

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 explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect