LLDB MCP Server

Instructions

Implementation Reference

• lldb_mcp_server.py:1096-1151 (handler)

  The main handler function for the 'lldb_run' tool, including decorator. It sets up LLDB commands to load the target, set breakpoints and environment, run the program, capture backtrace and frame variables, and formats the output.
  @mcp.tool( name="lldb_run", annotations={ "title": "Run Program", "readOnlyHint": False, "destructiveHint": False, "idempotentHint": False, "openWorldHint": True, }, ) async def lldb_run(params: RunProgramInput) -> str: """Run a program under the debugger with optional breakpoints. This tool: 1. Loads the executable 2. Sets any specified breakpoints 3. Runs the program (optionally stopping at entry) 4. Returns the state when stopped Args: params: RunProgramInput with executable, args, and breakpoints Returns: str: Program state after stopping (backtrace, variables) """ commands = [f"target create {params.executable}"] # Set environment variables if params.environment: for key, value in params.environment.items(): commands.append(f"settings set target.env-vars {key}={value}") # Set breakpoints if params.breakpoints: for bp in params.breakpoints: if ":" in bp and not bp.startswith("0x"): parts = bp.rsplit(":", 1) commands.append(f"breakpoint set --file {parts[0]} --line {parts[1]}") else: commands.append(f"breakpoint set --name {bp}") elif params.stop_at_entry: commands.append("breakpoint set --name main") # Prepare run command run_cmd = "run" if params.args: run_cmd += " " + " ".join(params.args) commands.extend([run_cmd, "thread backtrace", "frame variable", "quit"]) result = _run_lldb_script(commands, working_dir=params.working_dir) return ( f"## Program Run: `{Path(params.executable).name}`\n\n```\n{result['output'].strip()}\n```" )
• lldb_mcp_server.py:379-396 (schema)

  Pydantic BaseModel defining the input parameters for the lldb_run tool, including executable path, arguments, breakpoints, environment, stop_at_entry flag, and working directory.
  class RunProgramInput(BaseModel): """Input for running a program with debugging.""" model_config = ConfigDict(str_strip_whitespace=True) executable: str = Field(..., description="Path to the executable to run", min_length=1) args: list[str] | None = Field( default=None, description="Command-line arguments to pass to the program" ) breakpoints: list[str] | None = Field( default=None, description="List of breakpoint locations to set before running" ) environment: dict[str, str] | None = Field( default=None, description="Environment variables to set" ) stop_at_entry: bool = Field(default=True, description="Stop at the entry point (main function)") working_dir: str | None = Field(default=None, description="Working directory for the program")
• lldb_mcp_server.py:1096-1105 (registration)

  MCP tool registration decorator specifying the name 'lldb_run' and annotations for the tool.
  @mcp.tool( name="lldb_run", annotations={ "title": "Run Program", "readOnlyHint": False, "destructiveHint": False, "idempotentHint": False, "openWorldHint": True, }, )
• lldb_mcp_server.py:118-156 (helper)

  Helper function used by lldb_run to execute a sequence of LLDB commands in batch mode via subprocess.
  def _run_lldb_script( commands: list[str], target: str | None = None, working_dir: str | None = None, timeout: int = 60, ) -> dict[str, Any]: """ Execute multiple LLDB commands in sequence. """ cmd = [LLDB_EXECUTABLE] if target: cmd.extend(["--file", target]) cmd.append("--batch") for command in commands: cmd.extend(["-o", command]) try: result = subprocess.run( cmd, capture_output=True, text=True, timeout=timeout, cwd=working_dir or os.getcwd() ) return { "success": result.returncode == 0, "output": result.stdout, "error": result.stderr if result.returncode != 0 else None, "return_code": result.returncode, } except subprocess.TimeoutExpired: return { "success": False, "output": "", "error": f"Commands timed out after {timeout} seconds", "return_code": -1, } except Exception as e: return {"success": False, "output": "", "error": str(e), "return_code": -1}