1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@rr-mcp List available rr traces" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

rr-mcp

MCP (Model Context Protocol) server for orchestrating multi-process rr debugging sessions.

Overview

rr-mcp enables AI agents (like Claude) to debug multi-process applications using rr's record-and-replay capabilities. It provides:

48 specialized debugging tools with rich descriptions and usage context
Dynamic MCP resources that expose live session state (rr://sessions/{id})
Concurrent replay sessions for debugging different processes simultaneously
Full reverse execution — step, continue, and finish in both directions
Multi-process support — debug exec'd processes (pid) or forked-without-exec children (fork_pid)
Conditional and temporary breakpoints, watchpoints, and catchpoints (throw/catch/syscall/signal)

New to rr debugging? See RR_DEBUGGING_GUIDE.md for concepts, workflows, and best practices.

Requirements

Linux (rr only runs on Linux)
Python 3.11+
rr installed and in PATH
An rr recording to debug

Installation

Claude Code

claude mcp add rr-mcp -- uvx rr-mcp

Other MCP clients

Any MCP client that supports stdio servers can run uvx rr-mcp (or pipx run rr-mcp).

Installing from source

For development (recommended - no reinstall needed after changes):

git clone https://github.com/jnjaeschke/rr-mcp && cd rr-mcp
uv sync  # Install dependencies

# Configure Claude Code to run from source
claude mcp add rr-mcp -- uv run --directory /absolute/path/to/rr-mcp rr-mcp

For production use:

git clone https://github.com/jnjaeschke/rr-mcp && cd rr-mcp
uv tool install .

# Configure Claude Code
claude mcp add rr-mcp -- rr-mcp

For other MCP clients, use the appropriate command (uv run ... for development or rr-mcp for production).

Usage

Once installed, the server loads automatically when you start your MCP client. Verify it's working by asking:

"List available rr traces"

Claude will use the traces_list tool to show recordings in your _RR_TRACE_DIR (defaults to ~/.local/share/rr).

MCP Resources

rr://guide — Debugging guide with workflows, tool selection advice, and common pitfalls
rr://traces — Dynamic list of available recordings
rr://sessions/{id} — Current session state (position, location)
rr://sessions/{id}/backtrace — Live call stack for a session

Tools

48 debugging tools organized into categories. Each tool includes rich descriptions with usage context, parameter documentation, return value format specifications, and workflow guidance.

Trace Management (3 tools)

Tool	Description
`traces_list`	List all available rr recordings on the system
`trace_info`	Get metadata about a trace (creation time, binary, etc.)
`trace_processes`	List processes in a trace with PIDs and exec info

Session Lifecycle (3 tools)

Tool	Description
`session_create`	Create a replay session for a specific process. Supports `pid` (exec'd processes) and `fork_pid` (forked-without-exec children)
`session_list`	List all active replay sessions
`session_close`	End a session and free its resources

Execution Control (14 tools)

Tool	Description
`continue` / `reverse_continue`	Run forward/backward until breakpoint, signal, or end
`step` / `reverse_step`	Step by source lines, into functions
`next` / `reverse_next`	Step by source lines, over functions
`finish` / `reverse_finish`	Run to end/start of current function
`stepi` / `reverse_stepi`	Step by machine instructions, into calls
`nexti` / `reverse_nexti`	Step by machine instructions, over calls
`run_to_event`	Jump to a specific rr event number
`interrupt`	Stop a running program

Breakpoints & Watchpoints (7 tools)

Tool	Description
`breakpoint_set`	Set breakpoints by function, file:line, or address. Supports conditional (`condition`) and temporary breakpoints. Pending breakpoints are enabled automatically for unloaded code
`breakpoint_delete`	Delete a breakpoint by number
`breakpoint_list`	List all breakpoints with their state
`breakpoint_enable` / `breakpoint_disable`	Toggle breakpoints on/off
`watchpoint_set`	Break on memory writes, reads, or access to an expression
`catch`	Catchpoints for C++ `throw`/`catch`, syscalls (optionally filtered by name), and signals

Inspection (14 tools)

Tool	Description
`backtrace`	Call stack with optional `full` mode (includes locals per frame)
`print`	Evaluate an expression in the current context
`locals`	Local variables in the current frame
`args`	Function arguments across stack frames
`frame_select`	Switch to a different stack frame
`registers`	CPU registers (`gp_only` flag filters to general-purpose registers)
`examine_memory`	Formatted memory dump (like GDB's `x` command)
`when`	Current rr event and tick position
`threads_list` / `thread_select`	List and switch between threads
`checkpoint_create`	Save execution position for instant return later
`checkpoint_restore`	Jump back to a saved checkpoint
`checkpoint_delete` / `checkpoint_list`	Manage checkpoints

Signal Handling & Memory Search (2 tools)

Tool	Description
`handle_signal`	Configure how GDB handles a signal (stop, pass, print)
`find_in_memory`	Search memory range for a byte pattern

Source & Advanced (5 tools)

Tool	Description
`source_list`	Show source code around a location with context lines
`source_path`	Resolve a filename to its full path
`source_files`	List all source files in the program
`info`	GDB `info` subcommands (proc mappings, shared libs, symbols, types, signals)
`gdb_raw`	Execute an arbitrary GDB command (escape hatch)

All tools include detailed descriptions visible to Claude. See tool definitions in src/rr_mcp/server.py.

Example Session

Agent: Let me list the available traces.
[calls traces_list]

Agent: I see firefox-0. Let me check what processes are in it.
[calls trace_processes with trace="firefox-0"]

Agent: The main process is PID 12345, and there's a content process
       PID 12350 that crashed with SIGSEGV. Let me debug the content
       process — it forked without exec, so I need fork_pid.
[calls session_create with trace="firefox-0", fork_pid=12350]

Agent: Let me see where we are and get the crash backtrace.
[calls backtrace with session_id="abc123"]

Agent: Frame #3 in HandleEvent dereferences a null mWidget pointer.
       Let me see the source code around that line.
[calls source_list with location="HandleEvent.cpp:142"]

Agent: I'll set a watchpoint on mWidget to find where it was set to null,
       then reverse-continue to catch the moment it happened.
[calls watchpoint_set with expression="this->mWidget", access_type="write"]
[calls reverse_continue]

Agent: The watchpoint triggered at event 84021 in Widget::Destroy().
       Let me check who called this.
[calls backtrace]

Agent: I'll save this position as a checkpoint so I can return here later,
       then continue investigating the caller.
[calls checkpoint_create]

Development

# Install dev dependencies
uv sync --all-extras

# Run tests (parallel execution with pytest-xdist)
uv run pytest -n auto

# Run tests (sequential)
uv run pytest

# Run linter
uv run ruff check src/ tests/

# Run type checker
uv run mypy src/

License

MIT

rr-mcp

rr-mcp

Overview

Requirements

Installation

Claude Code

Other MCP clients

Installing from source

Usage

MCP Resources

Tools

Trace Management (3 tools)

Session Lifecycle (3 tools)

Execution Control (14 tools)

Breakpoints & Watchpoints (7 tools)

Inspection (14 tools)

Signal Handling & Memory Search (2 tools)

Source & Advanced (5 tools)

Example Session

Development

License

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API