Corellium Kernel LLDB MCP Server

A Model Context Protocol (MCP) server for managing LLDB kernel debugging sessions. This server connects LLDB to kernel debug ports (typically forwarded from Corellium devices) and provides a clean MCP interface for kernel debugging workflows.

Features

• PTY-based LLDB session management - Proper terminal emulation for interactive LLDB
• MCP resource exposure - Sessions are discoverable as MCP resources
• Multiple concurrent sessions - Debug multiple kernels simultaneously
• Clean error handling - Clear feedback when connections fail
• Stateless design - No coupling to specific device management systems

Setup

1. Create Virtual Environment

python3.12 -m venv venv/
source venv/bin/activate  # On Windows: venv\Scripts\activate

2. Install Dependencies

pip install -e .

3. Add to Claude Code

After completing the setup steps above, add the MCP server to Claude Code:

claude mcp add --scope user kernel-lldb -- <path-to-this-repo>/venv/bin/corellium-kernel-lldb-mcp

Replace <path-to-this-repo> with the actual path to this repository.

Usage

Run with stdio transport (default)

corellium-kernel-lldb-mcp

Run with HTTP transport

corellium-kernel-lldb-mcp --http --host 127.0.0.1 --port 8000 --path /mcp

Test with MCP Inspector

npx @modelcontextprotocol/inspector --cli corellium-kernel-lldb-mcp

Kernel Debugging Workflow

This server is designed to work alongside the Corellium MCP server for complete kernel debugging workflows.

Step 1: Set Up Port Forwarding (via Corellium MCP)

First, establish an SSH tunnel to the kernel debug port:

# Using Corellium MCP tools
start_kernel_debug_port_forward(
    instance_id="your-device-id",
    local_port=4000  # Default kernel debug port
)

This creates a tunnel: localhost:4000 -> device_services_ip:4000

Step 2: Download Kernel Binary (via Corellium MCP)

Download the kernel binary for symbol resolution:

# Using Corellium MCP tools
download_kernel_binary(
    instance_id="your-device-id",
    model="iPhone8,1",
    ios_version="19A404",
    filepath="/tmp/kernel-iPhone8,1-19A404"
)

Step 3: Start LLDB Session (this server)

Connect LLDB to the forwarded port:

session_id = lldb_start(
    port=4000,
    kernel_path="/tmp/kernel-iPhone8,1-19A404"
)
# Returns: "LLDB session started: abc-123-def-456"

Step 4: Debug the Kernel

Execute LLDB commands through the session:

# Get backtrace
lldb_command(session_id, "bt")

# Read registers
lldb_command(session_id, "register read")

# Examine memory
lldb_command(session_id, "memory read 0xfffffff007a04000")

# Lookup symbols
lldb_command(session_id, "image lookup --address 0xfffffff007a04000")

# Disassemble
lldb_command(session_id, "disassemble --start-address 0xfffffff007a04000 --count 20")

# Set breakpoints (if kernel supports it)
lldb_command(session_id, "breakpoint set --name panic")

# View threads
lldb_command(session_id, "thread list")

Step 5: Clean Up

lldb_terminate(session_id)

Tools

lldb_start

Start an LLDB kernel debugging session.

Parameters:

• port (int, optional): Local port where kernel debug server is listening (default: 4000)
• kernel_path (str): Path to kernel Mach-O binary for symbols

Returns: Session ID string (UUID)

Example:

{
  "port": 4000,
  "kernel_path": "/tmp/kernel-iPhone8,1-19A404"
}

lldb_command

Execute an LLDB command in an active session.

Parameters:

• session_id (str): Session ID from lldb_start
• command (str): LLDB command to execute

Returns: Command output

Example:

{
  "session_id": "abc-123-def-456",
  "command": "bt"
}

lldb_terminate

Close an LLDB session and clean up resources.

Parameters:

• session_id (str): Session ID to terminate

Example:

{
  "session_id": "abc-123-def-456"
}

lldb_list_sessions

List all active LLDB debugging sessions.

Returns: Array of session objects with metadata

Example Response:

[
  {
    "session_id": "abc-123-def-456",
    "port": 4000,
    "kernel_path": "/tmp/kernel-iPhone8,1-19A404",
    "status": "debugging",
    "target": "localhost:4000",
    "created": "2025-09-30T12:34:56.789Z",
    "ready": true
  }
]

MCP Resources

Active LLDB sessions are exposed as MCP resources for discoverability:

Resource URI Format: lldb-session://{session_id}

Resource Content:

{
  "session_id": "abc-123-def-456",
  "port": 4000,
  "kernel_path": "/tmp/kernel-iPhone8,1-19A404",
  "status": "debugging",
  "target": "localhost:4000",
  "created": "2025-09-30T12:34:56.789Z",
  "ready": true
}

Common LLDB Commands for Kernel Debugging

Basic Information

target list              # Show current target info
image list              # List loaded images/modules
thread list             # List all threads
bt                      # Backtrace (call stack)
frame info              # Current frame information

Memory Examination

memory read 0xaddr                          # Read memory at address
memory read --size 4 --format x --count 16  # Formatted memory read
x/20xg 0xaddr                               # Examine 20 giant words (hex)

Registers

register read                # Read all registers
register read pc sp lr       # Read specific registers
register write pc 0xaddr     # Write to register

Symbol Resolution

image lookup --address 0xaddr              # Find symbol at address
image lookup --name symbol_name            # Find address of symbol
image lookup --type type_name              # Find type definition

Disassembly

disassemble --start-address 0xaddr --count 20
disassemble --name function_name

Breakpoints (if supported)

breakpoint set --name panic
breakpoint set --address 0xaddr
breakpoint list
breakpoint delete 1

Control Flow (if kernel is running)

continue                # Continue execution
step                    # Step into
next                    # Step over
finish                  # Step out

Error Handling

Connection Refused

If you see error: Connection refused, it means:

• Port forwarding is not set up
• The kernel debug port is not listening
• Wrong port number specified

Solution: Set up port forwarding first using Corellium MCP tools.

Symbol Loading Issues

If symbols don't load properly:

• Verify kernel binary path is correct
• Ensure kernel binary matches the running kernel version
• Check file permissions on kernel binary

Development

This server is built using FastMCP and uses PTY-based LLDB process management for proper terminal emulation.

Architecture

• lldb_session.py - PTY-based LLDB session manager
• server.py - MCP tool definitions and resource management
• Resources - Active sessions exposed as lldb-session:// URIs