Architecture

Overview

pwndbg-lldb-mcp is a single-file MCP server (pwndbg_lldb_mcp.py) that bridges AI assistants to pwndbg running under LLDB. It exposes 146 tools covering the full range of pwndbg’s debugging, analysis, and exploit development commands.

PTY Communication

The server communicates with LLDB+pwndbg through a PTY (pseudo-terminal) pair:

  • The parent process holds the master fd and writes commands / reads output

  • The LLDB child process uses the slave fd as its terminal

  • Prompt detection ((pwndbg-lldb), pwndbg>, (lldb)) determines when a command has finished executing

  • All I/O is async with a 30-second timeout per command (longer than plain LLDB since pwndbg commands do more work)

Session Model

Each debugging session is managed by a PwndbgSession instance:

  • Sessions are identified by a UUID generated at creation time

  • Multiple sessions can run concurrently (each with its own LLDB process)

  • Session lifecycle: pwndbg_start → use tools → pwndbg_terminate

  • The pwndbg_list_sessions tool shows all active sessions

The pwndbg_command tool serves as an escape hatch — any pwndbg or LLDB command can be executed directly through it, even if no dedicated tool exists.

Tool Categories

Tools are organized into the following categories:

Session Management

Start, terminate, and list debugging sessions.

Program Loading

Load executables, attach to processes, load core dumps.

Execution Control

Run, step, next, finish, continue, and advanced stepping (nextjmp, nextcall, nextret).

Breakpoints & Watchpoints

Set, delete, enable/disable breakpoints and watchpoints.

Context & Display

pwndbg’s flagship context display — registers, disassembly, stack, backtrace.

Memory Inspection

Telescope, hexdump, vmmap, search, memory read/write, and string extraction.

Registers & CPU State

Read/write registers, view FPU state, CPUID, and CPU features.

Disassembly

nearpc, pdisass, emulate (single-step emulation via Unicorn).

Stack & Arguments

argv, retaddr, dumpargs, canary, stack frames, backtrace.

ELF / Binary Analysis

checksec, GOT/PLT, PIE offsets, ELF headers, sections, dynamic linking.

Heap Analysis

glibc ptmalloc2 introspection — arena, bins, chunks, top chunk, tcache.

Thread Tools

Thread listing, TLS inspection.

Exploit Development

Cyclic patterns, ROP gadget search, memory patching, assembler/disassembler, XOR.

Process Information

procinfo, ASLR status, auxv, libc info, errno.

WinDbg Compatibility

WinDbg-style memory dump and edit commands (db, dw, dd, dq, etc.).

Darwin / macOS

commpage inspection, plist viewing.

Configuration & Meta

pwndbg config, theme, tips, version.

LLDB Native Inspection

Expression evaluation, type lookup, image list, target info.

Integrations

Radare2 and Rizin integration.

Kernel Debugging

Linux kernel debugging via QEMU/KVM or kgdb — kchecksec, ksymbol, slab, paging.