RV MCP 서버

Claude와 같은 AI 어시스턴트를 업계 표준 미디어 리뷰 애플리케이션인 Autodesk/Tweak RV와 연결하는 MCP(Model Context Protocol) 서버입니다. 자연어를 통해 재생 제어, 샷 비교, 색 보정 조정 및 리뷰 세션 관리를 수행할 수 있습니다.

RV 내부에 별도의 플러그인이 필요하지 않습니다. remote-eval을 통한 Mu 스크립팅과 RV의 내장 네트워크 리스너를 사용합니다.

요구 사항

OpenRV (또는 RV 2022.3.1 이상), 네트워크 모드 활성화 상태
Python 3.10+
uv 패키지 관리자

빠른 시작

1. 네트워킹과 함께 RV 시작

RV → Networking → Enable Network(기본 포트 45124)를 통해 RV에서 네트워킹을 활성화합니다.

또는 명령줄에서 실행합니다:

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을 통한 스레드 안전성
DISCONNECT를 전송하는 atexit 핸들러를 통한 깔끔한 종료(이 과정이 없으면 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를 자동으로 구성하는 rv_ocio_setup.py 스크립트가 포함되어 있습니다:

EXR/HDR/TX 파일은 장면 선형(scene-linear, 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`	현재 OCIO 노드 상태를 JSON으로 가져옵니다
`clear_ocio`	OCIO 노드를 제거하고 기본 파이프라인을 복원합니다

Redshift + RV 색상 일치

Redshift의 OCIO 구성($OCIO = C:\ProgramData\redshift\Data\OCIO\config.ocio)을 사용하는 경우, 해당 파일 규칙이 EXR을 "Raw"로 표시한다는 점에 유의하세요. rv_ocio_setup.py 스크립트는 부동 소수점 형식을 장면 선형으로 감지하여 이를 재정의하며, Redshift의 렌더 뷰와 마찬가지로 RV에서도 ACES 톤매퍼가 적용되도록 합니다.

도구 (총 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`	현재 OCIO 상태를 JSON으로 가져오기
`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`	재생 초당 프레임 수(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

문제 해결

"Could not connect to 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