karellen-rr-mcp

MCP Server for rr Reverse Debugging (karellen-rr-mcp)

Overview

karellen-rr-mcp is an MCP (Model Context Protocol) server that enables any MCP-compliant LLM client to use rr for reverse debugging. Instead of iteratively adding debug output and rebuilding, the LLM can record a failing test with rr, then replay it with full forward and reverse debugging via GDB/MI, inspecting program state without modifying source code.

Requirements

• Linux on x86-64 (rr only supports Linux; aarch64 is experimental)
• rr installed and on PATH
• GDB installed and on PATH (used by rr for debugging)
• Python >= 3.10
• perf_event_paranoid set to 1 to allow recording:

  sudo sysctl kernel.perf_event_paranoid=1
  

Installing rr and GDB

Via pip (using karellen-rr):

pip install karellen-rr-mcp[rr]

This installs rr as a pip package alongside karellen-rr-mcp. GDB must still be installed separately via your system package manager.

Fedora / RHEL / CentOS:

sudo dnf install rr gdb

Ubuntu / Debian:

sudo apt install rr gdb

Arch Linux:

sudo pacman -S rr gdb

Configuring perf_event_paranoid

rr requires access to hardware performance counters. Set perf_event_paranoid to 1:

sudo sysctl kernel.perf_event_paranoid=1

To make this persistent across reboots:

echo 'kernel.perf_event_paranoid=1' | sudo tee /etc/sysctl.d/50-rr.conf

Verify the setup

rr record /bin/true && echo "rr is working"

If this fails with a permissions error, check perf_event_paranoid. If it fails inside a container or VM, note that rr requires access to CPU performance counters — it does not work in most containers (Docker, Podman) or VMs unless hardware PMU passthrough is configured.

Installation

pip install karellen-rr-mcp

Or with pipx for an isolated environment:

pipx install karellen-rr-mcp

Claude Code Integration

Claude Code plugin (recommended)

The plugin automatically configures the MCP server and includes:

• Crash detection hook that suggests rr when a Bash command exits with a signal (SIGSEGV, SIGABRT, SIGBUS, etc.) or output contains crash/sanitizer signatures
• /karellen-rr-mcp:rr-debug skill that walks through the full record-replay-analyze workflow step by step
• rr-investigator agent that Claude can spawn to autonomously investigate crashes using rr reverse execution

From the Karellen plugins marketplace:

claude plugin marketplace add karellen/claude-plugins
claude plugin install karellen-rr-mcp@karellen-plugins

Or from the official Anthropic marketplace (if accepted):

claude plugin install karellen-rr-mcp@claude-plugins-official

Or load directly from a local checkout for testing:

claude --plugin-dir /path/to/karellen-rr-mcp

Manual MCP server configuration

If you prefer not to use the plugin, you can configure the MCP server directly. This gives you the MCP tools but not the skill, agent, or crash detection hook.

Using the CLI:

claude mcp add --transport stdio karellen-rr-mcp -- karellen-rr-mcp

Or manually add to ~/.claude.json (user scope) or .mcp.json in your project root (project scope, shared via version control):

{
  "mcpServers": {
    "karellen-rr-mcp": {
      "type": "stdio",
      "command": "karellen-rr-mcp"
    }
  }
}

If installed with pipx:

claude mcp add --transport stdio karellen-rr-mcp -- pipx run karellen-rr-mcp

or manually: