davinci-resolve-lite-mcp

https://github.com/user-attachments/assets/8429932f-643b-4131-bdf6-dad0d3399137

Claude가 자연어로 된 요청 하나를 받아 DaVinci Resolve Lite에 오프닝 타이틀 — 글로우 효과와 줌인 키프레임 연출이 있는 금색 "GameHelper" Text+ 노드 — 을 insert_fusion_title + style_fusion_title로 만듭니다.

AI 클라이언트(예: Claude Code)가 DaVinci Resolve를 제어할 수 있게 해 주는 MCP 서버입니다. 기존 davinci-resolve-mcp 프로젝트로는 제어할 수 없었던 무료 (Lite) 에디션도 지원합니다.

무료 에디션은 외부 스크립팅을 차단하지만, Resolve 자신의 Workspace > Scripts 메뉴에서 실행한 Python 스크립트는 그대로 실행합니다. 이 프로젝트는 그 경로를 이용합니다. MCP 서버는 Resolve 내부에서 메뉴 스크립트로 실행되며, Claude가 연결하는 작은 로컬 HTTP 엔드포인트를 통해 Resolve의 Python API를 노출합니다.

Claude Code ──HTTP JSON-RPC (MCP)──▶  127.0.0.1:8765/mcp
                                          │   server runs INSIDE Resolve
                                          │   (Workspace > Scripts > Utility)
                                          ▼
                              command queue → main script thread
                                          ▼
                              global `resolve` object → Resolve API

도구

Claude에게 평범한 문장으로 요청하세요. 그러면 도구를 통해 Resolve를 제어합니다 — 위 데모를 참고하세요. 전체 163개 도구 범위에 대해서는 도구 참조를 확인하세요 — 편집, 컬러, 렌더, 미디어 풀, Fusion 타이틀 스타일링.

Related MCP server: resolve-mcp

무료 에디션에서 작동하는 이유

• 무료 Resolve는 Scripts 메뉴에서 실행된 스크립트를 허용합니다 (외부 *네트워크 스크립팅만 제한됩니다).

• 메뉴 스크립트는 resolve 개체를 자동으로 받아 서버를 호스팅할 수 있는 동안 실행되는 장기 루프를 돌릴 수 있습니다.

• 샌드박스 처리된 Lite 앱에는 com.apple.security.network.server 자격(entitlement)이 포함되어 있어 localhost 수신 소켓을 열 수 있습니다.

• 의존성 제로 — 순수 Python 표준 라이브러리입니다. Resolve의 인터프리터에 pip install 할 것이 없습니다.

요구 사항

• macOS와 DaVinci Resolve 설치 (Lite/무료 또는 Studio)

• Claude Code (또는 Streamable HTTP 전송을 사용할 수 있는 모든 MCP 클라이언트)

설치

git clone https://github.com/2sem/davinci-resolve-lite-mcp.git
cd davinci-resolve-lite-mcp
./install.sh

저장소를 클론하지 않고 pip으로 설치하려면:

pip install davinci-resolve-lite-mcp
davinci-mcp-install

davinci-mcp-install은 install.sh가 하는 것을 그대로 수행합니다 (동일한 Lite/Studio 감지, 동일한 복사 대 심링크 로직) — git 체크아웃 대신 pip으로 설치한 패키지에서 파일을 읽을 뿐입니다. davinci-mcp-uninstall은 그것을 되돌립니다. 어느 쪽이든 아래의 샌드박스 참고 사항은 그대로 적용되며, 여전히 Resolve 자체 메뉴에서 서버를 시작해야 합니다 — 실행을 참고하세요.

macOS 사용자 설치 참고. 만약 Defaulting to user installation because normal site-packages is not writeable이 표시된다면, pip가 콘솔 스크립트를 $(python3 -m site --user-base)/bin 아래에 설치한 것이며, 이 디렉터리는 보통 PATH에 없습니다. 전체 경로로 실행하거나 — "$(python3 -m site --user-base)/bin/davinci-mcp-install" — 그 bin 디렉터리를 PATH에 추가하세요. 두 명령 사이에는 &가 아니라 &&를 사용하세요: 한 개의 &는 pip 설치를 백그라운드로 실행하고, 패키지가 아직 없는데 davinci-mcp-install이 동시에 실행되는 경쟁이 됩니다.

또한 MCP Registry에 io.github.2sem/davinci-resolve-lite-mcp로 등재되어 있습니다 (확인) — 단지 검색 가능성을 위한 것입니다. 이 목록은 메타데이터만 제공합니다(자동 설치 packages/remotes 엔트리 없음). 이 서버는 일반적인 레지스트리 서버처럼 MCP 클라이언트가 기동할 수 없습니다. Resolve 내장 Python 인터프리터 안에서 실행되어야 하며 Scripts 메뉴에서 손으로 시작해야 하기 때문입니다. 위 두 방법 중 하나로 설치하세요.

install.sh가 배포하는 것:

• 두 런처 스크립트를 Fusion/Scripts/Utility에 (Resolve가 Scripts 메뉴를 위해 스캔하는 폴더; Utility 유틸은 모든 페이지에 표시됩니다), 그리고

• resolve_mcp 패키지를 Fusion/Scripts/MCP에 — Resolve가 스캔하지 않는 폴더이므로, 헬퍼 모듈이 메뉴에 나타나지 않는 폴더에 배치합니다.

Lite 컨테이너 경로가 자동으로 감지됩니다.

샌드박스 참고 사항(중요). DaVinci Resolve Lite는 샌드박스 되어 있고 자신의 컨테이너, ~/Movies, 그리고 사용자가 대화형으로 선택한 파일만 읽을 수 있습니다. 그 위치 밖을 가리키는 심링크(예: ~/Projects 아래 클론)는 샌드박스 앱이 따라갈 수 없기 때문에 메뉴 스크립트가 조용히 실행되지 않을 수 있습니다. 그 때문에 install.sh는 Lite에서 파일을 컨테이너로 복사합니다(그리고 샌드박스 아닌 Studio 빌드에서만 심링크를 생성합니다). 업데이트를 가져온 후 ./install.sh를 다시 실행하세요.

Resolve는 Scripts 메뉴를 위해 카테고리 폴더(Utility / Comp / Tool / Edit / Color / Deliver)만 열거합니다. 그래서 런처는 Utility에 들어가고 패키지는 MCP에 숨겨져 있습니다.

동일한 샌드박스 제한은 도구에 사용하도록 제공하는 파일 경로에도 적용됩니다. 내보내기/불러오기는 ~/Movies (또는 허용된 다른 위치)를 대상으로 해야 합니다. 그렇지 않으면 Resolve가 쓰거나 읽을 수 없습니다.

실행

1. DaVinci Resolve에서: Workspace > Scripts > Utility > davinci_mcp_server.

   

2. Workspace > Console을 엽니다 — 엔드포인트와 포트가 출력됩니다:

   MCP endpoint:  http://127.0.0.1:8765/mcp
   Add to Claude Code:
     claude mcp add --transport http davinci http://127.0.0.1:8765/mcp

   시작 가이드는 Resolve Console(Workspace > Console)에 출력됩니다. 서버가 계속 실행 중이기 때문에 Console 출력이 중지될 때까지 버퍼링될 수 있습니다. 그래서 두 스크립트는 모든 라인을 로그 파일에도 기록합니다:

   ~/Movies/davinci-resolve-lite-mcp.log

   ./logs.sh로 실시간으로 지켜보세요. (디렉터리는 DAVINCI_MCP_LOG_DIR로 덮어쓸 수 있습니다.) ~/Movies가 사용되는 이유는 샌드박스된 Lite 앱이 그곳에 쓰는 것을 허용하기 때문입니다.

   실행 중에는 모든 도구 호출이 Console에 한 줄씩 기록됩니다([davinci-mcp] <name> <args> -> ok|error (Nms)):

   

   업데이트 확인. It works like brew/CocoaPods — 각 실행에서 PyPI에서 더 새로운 릴리스가 있는지 백그라운드로 확인하고, 있으면 Console에 한 줄 안내(new one-liner)를 출력합니다. 시작을 막지 않고, 오류(오프라인, PyPI 다운)는 로그 파일에만 남습니다. 해제하려면 DAVINCI_MCP_SKIP_UPDATE_CHECK=1을 사용하세요.

3. Claude Code에 등록(한 번만):

   claude mcp add --transport http davinci http://127.0.0.1:8765/mcp

   그 다음 Claude Code 내부의 /mcp 명령으로 확인/연결을 재설정하세요. 연결된 서버를 나열하고 다시 연결해 줍니다. 이미 Claude가 켜져 있는 상태에서 스크립트를 실행했다면 /mcp를 입력(또는 세션 다시 시작)하세요 — 그래야 davinci 서버를 인식합니다.

4. Claude에게 Resolve를 제어하라고 요청하세요.

포트 설정(안정적, 권장됨)

기본적으로 서버는 포트 8765에서 수신하며, 그 포트가 사용 중이면 8766, 8767, …으로 자동 증가합니다 (다른 로컬 도구가 이미 8765 점유했을 수 있음). 순위가 실행할 때마다 바뀔 수 있으므로 Claude에 등록한 URL이 이동 갈 수 있으며, 이렇게 표시됩니다:

Failed to reconnect to davinci: HTTP 404 at http://127.0.0.1:8765/mcp

포트를 완전히 고정하려면 작은 JSON 설정 파일을 두면 됩니다. 이렇게 포트는 pinned — 서버는 정확히 그 포트만 사용하고 절대 자동 증가하지 않습니다. 그래서 Claude에 한 번 등록하면 URL은 이동하지 않습니다.

~/Movies/davinci-resolve-lite-mcp.config.json을 만드세요:

{ "host": "127.0.0.1", "port": 8770 }

왜 ~/Movies이고 ~/.config가 아닌가? Lite 앱은 샌드박스되어 자신의 컨테이너, ~/Movies, 그리고 대화형으로 선택한 파일만 읽을 수 있습니다. ~/.config는 샌드박스 밖에 있어 Lite가 읽지 못합니다(그래서 로그 파일이 ~/Movies에 있는 것과 같은 이유). 서버는 비-샌드박스 Studio 빌드에서도 ~/.config/davinci-resolve-lite-mcp/config.json을 확인합니다. 그 경로가 관례적으로 사용됩니다.

그런 다음 서버를 다시 시작하고(Scripts > Utilities > stop_davinci_mcp_server, 그 다음 davinci_mcp_server) 고정된 포트에서 Claude Code를 한 번 등록하세요:

claude mcp add --transport http davinci http://127.0.0.1:8770/mcp

Console 배너는 확인 소스를 알려줍니다 — Port : pinned (from …) — will not auto-increment를 확인하십시오:

해결 순서 (우선순위 높은 순) : DAVINCI_MCP_PORT / DAVINCI_MCP_HOST 환경 변수, 그 다음 구성 파일, 마지막으로 기본값입니다. 환경 변수도 포트를 고정하지만 Dock에서 시작된 Resolve는 셸 export를 보지 못합니다. 구성 파일이 가장 간단하고 영구적인 옵션입니다. DAVINCI_MCP_CONFIG=/path/to.json 파일이 특정 구성 파일만 유일하게 사용하며 — 경로가 없거나 잘못되면 서버는 ~/Movies / XDG를 읽는 대신 내장 기본값으로 대체됩니다.

만약 포트가 이미 변경되어 Claude가 잘못된 포트를 가리켰다면 다시 지정하세요:

claude mcp remove davinci
claude mcp add --transport http davinci http://127.0.0.1:<actual-port>/mcp

중지

다음 중 하나로 서버를 중지합니다:

• 메뉴에서: Workspace > Scripts > Utility > stop_davinci_mcp_server

• 터미널에서: ./stop.sh

• DaVinci Resolve 종료

메뉴 중지 스크립트와 stop.sh는 모두 서버의 /shutdown 엔드포인트에 POST 하고, 시작할 때 서버가 사용하는 것과 같은 포트 범위를 스캔합니다.

포트는 pinned로 설정하지 않았을 때만 8765에서 자동 증가합니다. 출시 때마다 URL이 절대 변하지 않도록 고정하려면 포트 설정를 참조하세요.

도구

163개 도구로 전체 파이프라인을 다루습니다:

• 상태 및 탐색 — 페이지 전환, 프로젝트/타임라인 설정

• 프로젝트 및 타임라인 — 로드/생성/복제, 마커, scene cuts, 수명 주기

• 트랙 — 추가/삭제, 활성화/잠금/이름 변경

• 편집 — 클립 배치/추가/삭제, 타이틀/생성기, 변형/크롭/줌

• 미디어 풀 및 스토리지 — 가져오기/삭제, 속성/메타데이터, 태그, 디스크 브라우즈

• 컬러 — 노드 그래프 LUT/활성화, 등급 초기화, 스틸

• 렌더 및 내보내기 — 렌더 대기열, 형식/코덱, 프레임/타임라인/프로젝트 내보내기/가져오기

자세한 도구별 참조는 docs/TOOLS.md 참조하세요.

모든 툴 호출은 Resolve Console과 로그 파일에 라인 하나로 기록됩니다: [davinci-mcp] <name> <args> -> ok|error|EXCEPTION (Nms).

프로젝트 레이아웃

src/davinci_mcp_server.py        thin launcher (deployed to Scripts/Utility)
src/stop_davinci_mcp_server.py   stop launcher
src/resolve_mcp/                 the server package (deployed to Scripts/MCP, hidden)
    config · logio · connection · bridge · tools · server
tests/test_server.py             offline tests (fake Resolve, no app needed)
install.sh · uninstall.sh · stop.sh · logs.sh
docs/TOOLS.md                    full per-tool reference
fallbacks/                       documented gotchas + fixes

테스트

• 오프라인 (Resolve 없음, 서버 없음) — import + 디스패처 + 툴 수 스모크:

  python3 tests/test_server.py

• 라이브 통합 — 실행 중인 서버에 대해 각 도구 단위 테스트 하나씩 (Resolve 열고 프로젝트 + 미디어 클립 있으며 davinci_mcp_server 실행된 상태):

  python3 tests/live_test.py                 # all features
  python3 tests/live_test.py set_timecode    # run the test(s) for given feature(s)

  각 테스트 이름은 도구 이름과 같으므로 어떤 도구를 고치면 그 테스트만 실행할 수 있습니다: python3 tests/live_test.py <tool>. 테스트는 되돌릴 수 있습니다(임시 타임라인 + 임시 파일, 정리됨). 파일에 의존하나나 세션에 축적되지 않는 도구는 오류 경로를 통해 확인됩니다. Studio 전용 / 무거운 복잡도 도구(예: detect_cuts, render_current_timeline, quick_export)는 이유를 남기고 건너뜁니다. 마커/스틸 과 몇몇 테스트는 깨끗한 Resolve 세션 상태에 따라 달라집니다. 실패하면 새로 시작 후 다시 실행됩니다.

기여

도구를 추가하는 방법, 스위트를 실행하는 방법, stdlib-only / Lite-first 제약, 출시 흐름은 CONTRIBUTING.md를 참조하세요.

범위

이 서버는 무료(Lite) 에디션을 목표로 하며 의도적으로 거기서 실행되는 API만을 다룹니다. Studio · 유료 전용 기능은 고의적으로 제외합니다 (Lite에서 no-op 됐거나 오류), 즉: 오디오 트랜스크립션, 자막 추출, Magic Mask, Stabilize(respawn), Smart Reframe, Dolby Vision 분석, Voice Isolation, 클라우드 프로젝트/데이터베이스 관리. 남아 있는 미사용 메서드는 GetUniqueId, 캐시 모드, Fusion 컴포지션 내부, 테이스테이크, 스테레오/3D, 배치 및 오버레이(overlay) 사전 설정같이 단순 접근자(accessor) 뿐이며, 기능 구멍은 아닙니다.

알려진 제한 사항

• 클립은 name(현재 미디어 풀 폴더 안) 또는 id(id/ids, 모든 빈에서 확인 가능)로 지정할 수 있습니다 — 이름이 모호하거나 클립이 다른 폴더에 있는 경우에는 id/ids를 전달하세요.

• 도구의 인수는 각 도구의 JSON Schema(필수 필드, 기본 타입, enum)를 기준으로 검증됩니다. 형식이 잘못된 호출에는 잘못된 인수를 명시한 명확한 오류가 반환됩니다. 심층/중첩 스키마 제약 조건까지 모두 검사되지는 않습니다.

보안 참고 사항

서버는 127.0.0.1에만 바인딩되므로 사용자의 머신에서만 접근할 수 있습니다. 포트에 접근할 수 있는 로컬 프로세스에는 모두 DaVinci Resolve의 제어 권한이 노출되므로, 반드시 신뢰할 수 있는 머신에서만 실행하세요.

서버가 자체적으로 수행하는 유일한 외부 호출은 시작 시 업데이트 확인(현재 버전 번호를 확인하기 위한 PyPI 공개 JSON API로의 GET 요청 — 다른 데이터는 전송되지 않음)입니다. 외부 호출을 전혀 하지 않도록 하려면 DAVINCI_MCP_SKIP_UPDATE_CHECK=1로 비활성화하면 됩니다.

라이선스

MIT — LICENSE를 참조하세요.