Cài đặt và cấu hình DaVinci Resolve MCP

Bài này hướng dẫn cài DaVinci Resolve MCP để agent điều khiển DaVinci Resolve qua Model Context Protocol (MCP): yêu cầu hệ thống, bộ cài đa nền tảng, các MCP client được hỗ trợ, chế độ server và cấu hình thủ công.

Yêu cầu

• DaVinci Resolve 18.5 trở lên (macOS, Windows hoặc Linux). Bản Studio hỗ trợ trực tiếp external scripting. Bản miễn phí thì không, vì Blackmagic chỉ mở external scripting cho Studio, nhưng vẫn kết nối được qua cầu nối trong ứng dụng cho bản miễn phí, chạy bên trong Resolve từ menu Workspace ▸ Scripts (không bị khoá). Mọi hướng dẫn bên dưới đều giả định bạn dùng Studio, trừ khi dùng cầu nối này.
• Python 3.10+ (MCP SDK yêu cầu 3.10). 3.10–3.12 là lựa chọn ít rủi ro nhất; 3.13/3.14 cũng chạy trên các bản Resolve gần đây, xem bên dưới.
• DaVinci Resolve đang chạy, với Preferences > General > "External scripting using" đặt là Local, hoặc Network kèm RESOLVE_SCRIPT_HOST đặt bằng IP của máy chạy Resolve (127.0.0.1 nếu Resolve và MCP chạy cùng máy).

Gói bổ sung tùy chọn

Bản cài cốt lõi chỉ cần Python, ffmpeg và scripting API của Resolve. Một số tính năng cần thêm gói, và nếu thiếu gói, tính năng đó từ chối chạy và đưa dòng lệnh cài thay vì đoán:

python scripts/doctor.py báo gói nào đang có. media_analysis capabilities mô tả chi tiết hơn về bộ phân tích.

Cài các gói này vào đúng môi trường mà server chạy. Bản cài được quản lý (managed install) dùng virtualenv riêng, nên pip install từ một shell không liên quan sẽ đặt gói ở chỗ interpreter đó không bao giờ tìm tới. Hãy dùng pip của chính venv đó (<install>/venv/bin/pip, trên Windows là venv\Scripts\pip.exe) hoặc kích hoạt venv trước. Từ v2.98.2, các công cụ dòng lệnh đi kèm gói (ví dụ openai-whisper cài file thực thi whisper) được tự tìm trong thư mục script của venv; trước đó bạn phải tự thêm chúng vào PATH.

Trọng số model có giấy phép riêng, tách biệt với code nạp chúng.

Phạm vi đã xác minh trực tiếp dựa trên DaVinci Resolve 19.1.3 Studio cho bề mặt API gốc, cùng DaVinci Resolve 20.3.2 Studio cho các bổ sung scripting của Resolve 20.0–20.2.2. API beta của Resolve 21 được hoãn có chủ đích cho tới khi có bản ổn định.

Bắt đầu nhanh

# Make sure DaVinci Resolve Studio is running, then:
npx davinci-resolve-mcp setup

Launcher npm cài một bản được quản lý vào thư mục dữ liệu ứng dụng của người dùng, rồi chạy bộ cài Python đa nền tảng từ đó. Cấu hình MCP client trỏ thẳng tới môi trường ảo Python được quản lý và src/server.py, nên sau khi setup không cần Node nữa.

Cài từ mã nguồn:

git clone https://github.com/samuelgursky/davinci-resolve-mcp.git
cd davinci-resolve-mcp

python install.py

Bộ cài tự nhận diện nền tảng, tìm bản cài DaVinci Resolve, tạo môi trường ảo và cấu hình MCP client, tất cả trong một bước.

Bộ cài và MCP server kiểm tra cập nhật theo kiểu best-effort với bản release mới nhất trên GitHub. Phần kiểm tra của server chạy nền, giới hạn mỗi 24 giờ một lần và không bao giờ tự cài code. Đặt DAVINCI_RESOLVE_MCP_UPDATE_CHECK=0 để tắt, hoặc DAVINCI_RESOLVE_MCP_UPDATE_INTERVAL_HOURS để đổi chu kỳ.

Các MCP client được hỗ trợ

Bộ cài có thể tự cấu hình các client sau:

Bạn có thể cấu hình nhiều client cùng lúc, hoặc dùng --clients manual để nhận đoạn cấu hình copy-paste.

Với Autohand Code, đăng ký launcher được quản lý sau khi setup:

autohand mcp add davinci-resolve npx davinci-resolve-mcp server

Autohand tự thêm cờ -y của npx. Thêm --scope project sau mcp add để giữ đăng ký trong workspace hiện tại.

Tùy chọn của bộ cài

npx davinci-resolve-mcp setup                 # Interactive npm setup
npx davinci-resolve-mcp setup --clients all   # Configure all clients
npx davinci-resolve-mcp doctor                # Dry-run environment/config check
npx davinci-resolve-mcp server                # Launch the managed MCP server
npx davinci-resolve-mcp control-panel         # Launch the local control panel
npx davinci-resolve-mcp sync                  # Refresh the managed install only

python install.py                              # Interactive mode
python install.py --clients all                # Configure all clients
python install.py --clients cursor,claude-desktop  # Specific clients
python install.py --clients manual             # Just print the config
python install.py --dry-run --clients all      # Preview without writing
python install.py --no-venv --clients cursor   # Skip venv creation

Chế độ server

MCP server có hai chế độ:

Tool timeline_item của server compound có các action riêng cho các quy trình (workflow) thường gặp:

Bộ cài dùng server compound mặc định. Để dùng server full:

python src/server.py --full    # Launch full 389-tool server
# Or point your MCP config directly at src/resolve_mcp_server.py

Control panel cục bộ

Repo có một control panel cục bộ, một người dùng, để xem trạng thái server, clip trong Resolve, các job phân tích media an toàn với nguồn, và chỉ mục phân tích có thể tìm kiếm. Các job phân tích được lưu sẽ tự làm mới chỉ mục sau mỗi lát chạy thành công; nút Build Index thủ công dùng để dựng lại từ các báo cáo đã có.

Từ thư mục gốc repo:

venv/bin/python -m src.control_panel

Lệnh này mặc định mở trình duyệt. Dùng --no-open để chỉ chạy server localhost, hoặc --port để chọn cổng khác:

venv/bin/python -m src.control_panel --no-open --port 8766

Bạn cũng có thể nhờ agent lập trình: "Open the Resolve MCP control panel for this repo." Agent sẽ chạy lệnh trên và mở URL cục bộ.

Cấu hình thủ công

Nếu muốn tự thiết lập, thêm vào cấu hình MCP client:

{
  "mcpServers": {
    "davinci-resolve": {
      "command": "/path/to/venv/bin/python",
      "args": ["/path/to/davinci-resolve-mcp/src/server.py"],
      "env": {
        "RESOLVE_SCRIPT_API": "/path/to/DaVinci Resolve/Developer/Scripting",
        "RESOLVE_SCRIPT_LIB": "/path/to/fusionscript.so-or-dll",
        "PYTHONPATH": "/path/to/DaVinci Resolve/Developer/Scripting/Modules"
      }
    }
  }
}

Codex CLI dùng TOML. Thêm vào ~/.codex/config.toml (hoặc $CODEX_HOME/config.toml):

[mcp_servers.davinci-resolve]
command = "/path/to/venv/bin/python"
args = ["/path/to/davinci-resolve-mcp/src/server.py"]
env = { RESOLVE_SCRIPT_API = "/path/to/DaVinci Resolve/Developer/Scripting", RESOLVE_SCRIPT_LIB = "/path/to/fusionscript.so-or-dll", PYTHONPATH = "/path/to/DaVinci Resolve/Developer/Scripting/Modules" }

Đường dẫn phải là tuyệt đối, vì Codex không mở rộng ~. Chạy python install.py --clients codex để bộ cài ghi khối này giúp bạn (nó gộp vào cấu hình hiện có và giữ nguyên các server, comment khác).

Trên Windows, cấu hình do bộ cài sinh ra có thêm PYTHONHOME. Biến này giới hạn binding Python của Resolve vào interpreter đã chọn và tránh lỗi crash nhiều Python trên Resolve 20.3 được báo trong Issue #26.

Với chế độ scripting Network của Resolve, thêm "RESOLVE_SCRIPT_HOST": "127.0.0.1" vào object env ở trên, thay địa chỉ nếu Resolve chạy trên máy khác. Khi có biến này, server dùng lời gọi scriptapp nhắm IP tường minh của Resolve, với thời gian chờ kết nối có giới hạn. Đặt RESOLVE_SCRIPT_TIMEOUT bằng một số giây dương hữu hạn để thay mức mặc định 5 giây. Bộ cài đưa cả hai giá trị vào cấu hình client nếu chúng có trong môi trường của nó.

Cơ chế truyền tải (transport) qua mạng của chính MCP server (--transport streamable-http hoặc sse) mặc định bind 127.0.0.1:8000 và bắt buộc header Authorization: Bearer <token> ở mọi yêu cầu (request) (DAVINCI_MCP_TOKEN, hoặc một token được sinh tự động). Để phục vụ client trên máy khác, đặt DAVINCI_MCP_HOST là địa chỉ cần bind và, nếu client truy cập máy bằng tên DNS thay vì địa chỉ đó, liệt kê các tên trong DAVINCI_MCP_ALLOWED_HOSTS (phân cách bằng dấu phẩy). Transport luôn bật chống DNS-rebinding, gắn với host đang bind, loopback và các tên đó; yêu cầu có header Host không thuộc nhóm này sẽ nhận 421. Bind wildcard (0.0.0.0 / ::) mà không liệt kê tên nào sẽ tắt kiểm tra Host, vì client không bao giờ gửi wildcard làm Host, và khi đó bearer token là lớp bảo vệ duy nhất. Hãy giới hạn bind không phải loopback bằng firewall của máy.

Chạy doctor chỉ-đọc với chế độ Network một cách tường minh:

python3 scripts/doctor.py --resolve-host 127.0.0.1
python3 scripts/doctor.py --resolve-host resolve.example.test --resolve-timeout 12.5

Khi server compound đang chạy, resolve_control(action="get_version") trả về phiên bản MCP cục bộ, trạng thái kiểm tra cập nhật gần nhất và quyết định cập nhật hiện tại dưới khoá mcp. resolve_control(action="mcp_update_status", params={"force_check": true}) kiểm tra ngay ở foreground.

Chính sách cập nhật MCP

Server giữ việc kiểm tra cập nhật ở dạng không tương tác để khởi động MCP qua stdio luôn an toàn với mọi client. Bộ cài là nơi hỏi người dùng: khi có bản release mới trên GitHub, cài tương tác cho phép cập nhật ngay, tiếp tục, hoãn 24 giờ, bỏ qua bản đó, bật tự cập nhật an toàn, hoặc tắt kiểm tra cho bản checkout này.

Tự cập nhật an toàn chỉ chạy với git checkout sạch có upstream, và chạy git fetch --tags --prune rồi git pull --ff-only. Nếu checkout có thay đổi cục bộ, không có upstream, hoặc cập nhật không fast-forward được, bộ cài tiếp tục với bản hiện tại.

Cờ của bộ cài:

python install.py --update-now
python install.py --update-policy prompt
python install.py --update-policy auto
python install.py --update-policy notify
python install.py --update-policy never
python install.py --clear-update-preferences

Các mặc định cục bộ này cũng chỉnh được từ chat qua setup(action="get_defaults") và setup(action="set_defaults"). Ví dụ, {"defaults":{"updates":{"mode":"notify"}}} đổi chính sách cập nhật MCP mà không cần chạy lại bộ cài. updates.check_interval_hours và updates.snooze_hours cũng đặt được bằng tool setup này; biến môi trường vẫn được ưu tiên khi có.

Biến môi trường điều khiển:

DAVINCI_RESOLVE_MCP_UPDATE_CHECK=0
DAVINCI_RESOLVE_MCP_UPDATE_MODE=prompt|auto|notify|never
DAVINCI_RESOLVE_MCP_UPDATE_INTERVAL_HOURS=24
DAVINCI_RESOLVE_MCP_UPDATE_SNOOZE_HOURS=24
DAVINCI_RESOLVE_MCP_UPDATE_STATE=/path/to/update-check.json

Đường dẫn theo nền tảng:

Nguồn

• Dịch và biên tập từ https://raw.githubusercontent.com/samuelgursky/davinci-resolve-mcp/main/docs/install.md, giấy phép MIT.