RV MCP 服务器

MCP (Model Context Protocol) 服务器，将 Claude 等 AI 助手连接到行业标准媒体审阅应用程序 Autodesk/Tweak RV。通过自然语言控制播放、比较镜头、调整色彩分级并管理审阅会话。

RV 内部无需插件。使用 RV 内置的网络监听器，通过 remote-eval 执行 Mu 脚本。

要求

OpenRV (或 RV 2022.3.1+)，并启用网络模式
Python 3.10+
uv 包管理器

快速入门

1. 启动带有网络功能的 RV

通过 RV → Networking → Enable Network 启用 RV 中的网络功能（默认端口 45124）。

或者通过命令行：

rv -network -networkPort 45124

2. 安装与注册

Claude Code (CLI):

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

注意： --no-sync 可防止多个 Claude 会话共享同一个 MCP 服务器时出现文件锁冲突。在更改依赖项后手动运行 uv sync。

Claude Desktop (~/.claude.json):

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

环境变量 (可选):

变量	默认值	描述
`RV_MCP_HOST`	`127.0.0.1`	RV 网络主机
`RV_MCP_PORT`	`45124`	RV 网络端口

3. 使用方法

让 Claude 加载媒体、控制播放、比较镜头或调整颜色。服务器会自动将自然语言转换为 RV 命令。

架构

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

服务器使用基于 RV RvCommunicator 的自定义协议与 RV 保持 持久 TCP 连接。关键设计决策：

持久连接：在套接字丢失时自动重连
线程安全：通过 threading.Lock 实现并发工具调用
安全关闭：通过 atexit 处理程序发送 DISCONNECT（否则 RV 将拒绝后续连接）
Mu 字符串处理：返回值会自动取消引用和转义

协议流程

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 色彩管理

服务器包含完整的 OCIO v2 支持。当设置 $OCIO 时，RV 可以匹配 DCC 应用程序（3ds Max/Redshift、Nuke 等）使用的精确显示变换。

自动配置

包含一个 rv_ocio_setup.py 脚本，当 RV 加载媒体时会自动配置 OCIO：

EXR/HDR/TX 文件：自动检测为场景线性（通过 scene_linear 角色使用 ACEScg）
显示变换：根据配置的默认值设置（例如 sRGB / ACES 1.0 SDR-video）
色度元数据：EXR 中的色度元数据与活动配置的色彩空间相匹配

要安装，请将 rv_ocio_setup.py 复制到您的 RV 支持路径：

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

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

RV 内置的 ocio_source_setup 包将自动检测并使用此覆盖设置。

通过 MCP 进行手动 OCIO 操作

工具	描述
`get_ocio_config`	从活动 OCIO 配置中列出色彩空间、显示、视图和外观
`set_ocio_colorspace`	设置源的输入色彩空间（插入 OCIOFile 节点）
`set_ocio_display`	设置显示变换（插入 OCIODisplay 节点）
`set_ocio_look`	将 OCIO 外观应用于源
`get_ocio_state`	以 JSON 格式获取当前 OCIO 节点状态
`clear_ocio`	移除 OCIO 节点并恢复默认管线

Redshift + RV 色彩匹配

如果您使用 Redshift 的 OCIO 配置（$OCIO = C:\ProgramData\redshift\Data\OCIO\config.ocio），请注意其文件规则将 EXR 标记为“Raw”。rv_ocio_setup.py 脚本通过将浮点格式检测为场景线性来覆盖此设置，确保在 RV 中应用 ACES 色调映射，就像在 Redshift 的渲染视图中一样。

工具 (共 47 个)

执行 (1)

工具	描述
`execute_mu`	运行任意 Mu 代码 — 用于处理专用工具未涵盖的任何操作

OCIO (6)

工具	描述
`get_ocio_config`	获取 OCIO 配置信息（色彩空间、显示、视图、外观）
`set_ocio_colorspace`	设置源的 OCIO 输入色彩空间
`set_ocio_display`	设置 OCIO 显示变换
`set_ocio_look`	应用 OCIO 外观
`get_ocio_state`	以 JSON 格式获取当前 OCIO 状态
`clear_ocio`	移除 OCIO 节点，恢复默认设置

播放 (17)

工具	描述
`load_source`	加载媒体文件（图像序列、电影或单张图像）
`load_sources`	同时加载多个媒体文件
`play`	开始播放
`stop`	停止播放
`toggle_playback`	切换播放/停止，返回新状态
`get_frame`	获取当前帧号
`set_frame`	跳转到特定帧
`step_forward`	向前步进 N 帧（默认 1）
`step_backward`	向后步进 N 帧（默认 1）
`set_in_point`	设置入点（播放范围的开始）
`set_out_point`	设置出点（播放范围的结束）
`get_in_out_points`	以 JSON 格式获取当前入/出点
`set_fps`	设置播放帧率
`get_fps`	获取当前播放 FPS
`set_realtime`	启用/禁用实时模式（跳帧以保持 FPS）
`set_play_mode`	设置循环模式：`loop`、`once` 或 `pingpong`
`set_playback_speed`	设置播放方向和速度（1=正向，-1=反向，2=2倍速等）
`get_frame_range`	以 JSON 格式获取完整播放状态（帧、范围、入/出点、播放状态、FPS）

源 (7)

工具	描述
`get_sources`	以 JSON 数组列出所有已加载的源节点
`get_source_media_info`	获取详细媒体信息（分辨率、帧范围、FPS、位深、通道）
`get_sources_at_frame`	获取在特定帧可见的源节点
`new_session`	创建新的空会话
`clear_session`	清除当前会话中的所有源
`save_session`	将会话保存到 `.rv` 文件
`get_session_info`	以 JSON 格式获取会话状态（视图节点、帧范围、源计数）

比较 (4)

工具	描述
`set_view_mode`	切换视图：`sequence`（按顺序播放）、`stack`（分层比较）、`layout`（并排平铺）
`set_composite_type`	设置堆叠合成模式：`over`、`add`、`difference`、`-difference`、`replace`、`topmost`
`toggle_wipe`	切换 A/B 擦除比较（自动切换到堆叠视图）
`get_view_info`	以 JSON 格式获取当前视图状态

颜色 (12)

工具	描述
`set_lut`	在目标（`look`、`linearize`、`display`）上加载 LUT 文件（`.3dl`、`.csp`、`.cube` 等）
`clear_lut`	取消目标上的 LUT
`set_cdl`	设置 CDL 值（斜率、偏移、幂、饱和度） — 支持部分更新
`clear_cdl`	取消 CDL 色彩校正
`set_exposure`	设置曝光（按通道或统一）
`set_gamma`	设置伽马校正
`set_saturation`	设置饱和度
`get_color_settings`	以 JSON 格式获取当前色彩校正状态
`set_display_gamma`	设置显示伽马（例如 sRGB 类显示器为 2.2）
`set_display_srgb`	启用/禁用 sRGB 显示变换
`set_background`	设置视口背景：`black`、`checker`、`grey18`、`grey50`、`crosshatch`

使用示例

加载并审阅素材

"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"

比较两个版本

"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"

色彩校正

"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"

高级 (原始 Mu)

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

项目结构

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

故障排除

“无法连接到 RV”

确保 RV 在启动时带有 -network 标志
检查 45124 端口是否未被防火墙阻止
使用 -networkPort 45124 显式设置端口

RV 在崩溃后拒绝连接

如果服务器在未发送 DISCONNECT 的情况下退出，RV 可能会拒绝新连接。重启 RV 以清除状态。服务器包含一个 atexit 处理程序，以防止在正常操作下发生这种情况。

Mu 代码错误

始终将代码块包装在 { require commands; ... } 中
Mu 会评估 if/then/else 的两个分支 — 避免在可能不存在的节点上访问属性
文件路径必须使用正斜杠；escape_mu_string() 会自动处理此问题

超时错误

默认超时为 30 秒。如果 Mu 代码执行时间过长（例如加载大型序列），可能会超时。对于长时间操作，请使用 execute_mu 并考虑将其拆分为更小的步骤。

开发

# Install dependencies
uv sync

# Run the server directly
uv run rv-mcp

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

许可证

MIT

RV MCP Server