RV Server

MCP (Model Context Protocol) server that bridges AI assistants like Claude to Autodesk/Tweak RV, the industry-standard media review application. Control playback, compare shots, adjust color grading, and manage review sessions — all through natural language.

No plugin required inside RV. Uses RV's built-in network listener with Mu scripting via remote-eval.

Requirements

• OpenRV (or RV 2022.3.1+) with network mode enabled
• Python 3.10+
• uv package manager

Quick Start

1. Start RV with networking

Enable networking in RV via RV → Networking → Enable Network (default port 45124).

Or from the command line:

rv -network -networkPort 45124

2. Install and register

Claude Code (CLI):

claude mcp add --scope user rv-mcp -- uv run --no-sync --directory /path/to/RV_MCP rv-mcp

Note: --no-sync prevents file lock conflicts when multiple Claude sessions share the same MCP server. Run uv sync manually after changing dependencies.

Claude Desktop (~/.claude.json):

{
  "mcpServers": {
    "rv-mcp": {
      "command": "uv",
      "args": ["run", "--no-sync", "--directory", "/path/to/RV_MCP", "rv-mcp"]
    }
  }
}

Environment variables (optional):

Variable	Default	Description
RV_MCP_HOST	127.0.0.1	RV network host
RV_MCP_PORT	45124	RV network port

3. Use it

Ask Claude to load media, control playback, compare shots, or adjust colors. The server translates natural language into RV commands automatically.

Architecture

Claude (stdio/MCP) --> FastMCP Server --> RV Network Protocol (TCP:45124) --> RV

The server maintains a persistent TCP connection to RV using a custom protocol based on RV's RvCommunicator. Key design decisions:

• Persistent connection with automatic reconnection on socket loss
• Thread-safe via threading.Lock for concurrent tool calls
• Clean shutdown via atexit handler that sends DISCONNECT (without this, RV rejects future connections)
• Mu string handling — return values are automatically unquoted and unescaped

Protocol Flow

1. Connect TCP to 127.0.0.1:45124
2. Send: NEWGREETING <len> rv-mcp rvController
3. Send: PINGPONGCONTROL 1 0          (disable heartbeat)
4. Recv: NEWGREETING <len> <rv-name>   (consume RV's greeting)
5. For each command:
   Send: MESSAGE <len> RETURNEVENT remote-eval * { require commands; <mu_code> }
   Recv: MESSAGE <len> RETURN <value>
6. On shutdown:
   Send: MESSAGE <len> DISCONNECT

OCIO Color Management

The server includes full OCIO v2 support. When $OCIO is set, RV can match the exact display transform used by your DCC apps (3ds Max/Redshift, Nuke, etc.).

Auto-configuration

An rv_ocio_setup.py script is included that auto-configures OCIO when RV loads media:

• EXR/HDR/TX files are auto-detected as scene-linear (ACEScg via the scene_linear role)
• Display transform is set from the config's defaults (e.g., sRGB / ACES 1.0 SDR-video)
• Chromaticity metadata in EXRs is matched against the active config's color spaces

To install, copy rv_ocio_setup.py to your RV support path:

# Windows
copy rv_ocio_setup.py %APPDATA%\RV\Python\

# Linux/macOS
cp rv_ocio_setup.py ~/.rv/Python/

RV's built-in ocio_source_setup package will detect and use this override automatically.

Manual OCIO via MCP

Tool	Description
get_ocio_config	List color spaces, displays, views, and looks from the active OCIO config
set_ocio_colorspace	Set input color space for a source (inserts OCIOFile node)
set_ocio_display	Set display transform (inserts OCIODisplay node)
set_ocio_look	Apply an OCIO look to a source
get_ocio_state	Get current OCIO node state as JSON
clear_ocio	Remove OCIO nodes and restore default pipeline

Redshift + RV Color Matching

If you use Redshift's OCIO config ($OCIO = C:\ProgramData\redshift\Data\OCIO\config.ocio), note that its file rules mark EXRs as "Raw". The rv_ocio_setup.py script overrides this by detecting float formats as scene-linear, ensuring the ACES tonemapper is applied in RV just like in Redshift's Render View.

Tools (47 total)

Execute (1)

Tool	Description
execute_mu	Run arbitrary Mu code — escape hatch for anything not covered by dedicated tools

OCIO (6)

Tool	Description
get_ocio_config	Get OCIO config info (color spaces, displays, views, looks)
set_ocio_colorspace	Set OCIO input color space for a source
set_ocio_display	Set OCIO display transform
set_ocio_look	Apply an OCIO look
get_ocio_state	Get current OCIO state as JSON
clear_ocio	Remove OCIO nodes, restore defaults

Execute (1)

Tool	Description
execute_mu	Run arbitrary Mu code — escape hatch for anything not covered by dedicated tools

Playback (17)

Tool	Description
load_source	Load a media file (image sequence, movie, or single image)
load_sources	Load multiple media files at once
play	Start playback
stop	Stop playback
toggle_playback	Toggle play/stop, returns new state
get_frame	Get current frame number
set_frame	Jump to a specific frame
step_forward	Step forward by N frames (default 1)
step_backward	Step backward by N frames (default 1)
set_in_point	Set the in-point (start of playback range)
set_out_point	Set the out-point (end of playback range)
get_in_out_points	Get current in/out points as JSON
set_fps	Set playback frames per second
get_fps	Get current playback FPS
set_realtime	Enable/disable realtime mode (skip frames to maintain FPS)
set_play_mode	Set loop mode: loop, once, or pingpong
set_playback_speed	Set playback direction and speed (1=forward, -1=reverse, 2=2x, etc.)
get_frame_range	Get full playback state as JSON (frame, range, in/out, playing, fps)

Sources (7)

Tool	Description
get_sources	List all loaded source nodes as JSON array
get_source_media_info	Get detailed media info (resolution, frame range, fps, bit depth, channels)
get_sources_at_frame	Get source nodes visible at a specific frame
new_session	Create a new empty session
clear_session	Clear all sources from the current session
save_session	Save session to an .rv file
get_session_info	Get session state as JSON (view node, frame range, source count)

Compare (4)

Tool	Description
set_view_mode	Switch view: sequence (play in order), stack (layer for comparison), layout (tile side by side)
set_composite_type	Set stack composite mode: over, add, difference, -difference, replace, topmost
toggle_wipe	Toggle A/B wipe comparison (auto-switches to stack view)
get_view_info	Get current view state as JSON

Color (12)

Tool	Description
set_lut	Load a LUT file (.3dl, .csp, .cube, etc.) on a target (look, linearize, display)
clear_lut	Deactivate LUT on a target
set_cdl	Set CDL values (slope, offset, power, saturation) — partial updates supported
clear_cdl	Deactivate CDL color correction
set_exposure	Set exposure (per-channel or uniform)
set_gamma	Set gamma correction
set_saturation	Set saturation
get_color_settings	Get current color correction state as JSON
set_display_gamma	Set display gamma (e.g., 2.2 for sRGB-like)
set_display_srgb	Enable/disable sRGB display transform
set_background	Set viewport background: black, checker, grey18, grey50, crosshatch

Usage Examples

Load and review footage

"Load the EXR sequence at /shots/sh010/comp/sh010_comp.1-100#.exr"
"Play it back at 24fps"
"Go to frame 50"
"Set in point at 20 and out point at 80"

Compare two versions

"Load both /shots/sh010/comp_v1.mov and /shots/sh010/comp_v2.mov"
"Switch to stack view"
"Set composite to difference mode"
"Toggle the wipe to compare side by side"

Color correction

"Apply CDL with slope [1.1, 0.95, 1.0] and saturation 1.2"
"Load the ACES LUT from /luts/sRGB.cube"
"Set exposure to 0.5"
"Show me the current color settings"

Advanced (raw Mu)

"Execute this Mu code: { require commands; let s = sources(); string(s.size()); }"

Project Structure

RV_MCP/
├── pyproject.toml          # Package config, entry point, dependencies
├── README.md
├── .gitignore
└── src/
    ├── __init__.py
    ├── server.py           # FastMCP server + RvClient instantiation
    ├── rv_client.py        # Persistent TCP client (RV network protocol)
    └── tools/
        ├── __init__.py
        ├── execute.py      # execute_mu — raw Mu escape hatch
        ├── playback.py     # 17 playback/transport tools
        ├── sources.py      # 7 source & session tools
        ├── compare.py      # 4 view/compare tools
        ├── color.py        # 12 color/LUT/CDL tools
        └── ocio.py         # OCIO v2 color management tools

Troubleshooting

"Could not connect to RV"

• Ensure RV is running with the -network flag
• Check that port 45124 is not blocked by a firewall
• Use -networkPort 45124 to explicitly set the port

RV rejects connections after a crash

If the server exits without sending DISCONNECT, RV may reject new connections. Restart RV to clear the state. The server includes an atexit handler to prevent this under normal operation.

Mu code errors

• Always wrap code blocks in { require commands; ... }
• Mu evaluates both branches of if/then/else — avoid property access on nodes that may not exist
• File paths must use forward slashes; escape_mu_string() handles this automatically

Timeout errors

The default timeout is 30 seconds. If Mu code takes longer (e.g., loading large sequences), it may time out. Use execute_mu for long operations and consider breaking them into smaller steps.

Development

# Install dependencies
uv sync

# Run the server directly
uv run rv-mcp

# Run with debug logging
uv run python -m src.server

License

MIT