MCP Video Gen

ComfyUI, Blender 등 로컬 미디어 생성 백엔드를 노출하고 로컬 미디어 분석, 편집, FFmpeg, HyperFrames, 타임라인, 자막, 음성, 오디오 유틸리티를 제공하는 자체 호스팅 MCP 서버입니다.

이 프로젝트는 Portainer 전용 배포를 위해 설계되었습니다. 공개 저장소에는 일반 다중 파일 애플리케이션이 포함되어 있으며, 단일 video-mcp.yml Stack이 불변 GitHub 릴리스의 부트스트랩 로더 역할을 합니다.

기능

• ComfyUI가 사용 가능할 때 /object_info에 의해 실제로 등록된 ComfyUI 노드를 검색합니다.

• 마운트된 경우 읽기 전용 ComfyUI models/ 및 custom_nodes/ 디렉터리를 스캔합니다.

• 호환 가능한 사용자 정의 노드 소스/문서 파일을 검사합니다.

• 임의의 유효한 ComfyUI API 워크플로우 JSON을 제출하고 큐/히스토리/출력 상태를 검사합니다.

• 선택적으로 인증된 브리지를 통해 호스트에 설치된 Blender를 제어하여 bpy 자동화, 정지 렌더링, 애니메이션 렌더링 및 GLB 내보내기를 수행합니다.

• 텍스트, 원샷 base64 또는 청크 바이너리 전송을 사용하여 MCP 클라이언트/AI의 파일을 영구 캐시로 가져옵니다.

• 인증된 HTTP 다운로드, 인라인 base64 또는 제한된 청크 base64 읽기를 통해 캐시된 파일을 클라이언트/AI로 반환합니다.

• 하나의 file_id 계약을 통해 입력 업로드, 출력 캐시, 생성된 이미지, 비디오, 오디오, 3D, 장면, 자막 및 기타 파일을 검색합니다.

• HTML/CSS/미디어를 사용하여 로컬 HyperFrames 프로젝트를 생성하고 렌더링합니다.

• FFmpeg로 프로브, 트랜스코딩, 연결, 오버레이, 오디오 먹싱, 자르기, 역재생, 반복, 속도 램프 및 프레임 추출을 수행합니다.

• 무음, 검은색/정지 섹션, 음량, 인터레이스, 자르기 영역, 키프레임 및 객관적인 SSIM/PSNR 차이를 감지합니다.

• 연락처 시트/스토리보드를 만들고 가벼운 프레임 유사성, 모션, 중복 프레임 및 최적 프레임 분석을 수행합니다.

• PySceneDetect로 장면을 감지하고 분할합니다.

• pysubs2 + FFmpeg로 자막을 생성, 재시간 조정, 변환, 스타일 지정 및 번인합니다.

• 트랙, 클립, 전환, 마커, 재정렬, 검사 및 내보내기가 가능한 영구 OpenTimelineIO 타임라인을 유지 관리합니다.

• aubio로 비트, 템포, 온셋 및 피치를 감지합니다.

• RNNoise로 로컬에서 음성을 잡음 제거합니다.

• 소형 Silero VAD ONNX 모델로 음성 세그먼트를 감지합니다.

• whisper.cpp로 로컬에서 미디어를 전사하고, 자막을 생성하며, 단어 수준 타임스탬프를 얻습니다.

• 선택적으로 사용자 제공 Piper 음성으로 음성을 합성합니다. Piper는 기본적으로 비활성화되어 있습니다.

• 선택적으로 원본에서 Cloudflare Access JWT를 검증하고 Cloudflare Tunnel 사이드카를 실행합니다.

이 서버는 의도적으로 고정된 AI 생성 워크플로우, 장기 메모리 또는 에이전트 기술을 포함하지 않습니다. 실행 기본 요소를 노출하여 클라이언트 또는 별도의 지식/기술 MCP가 워크플로우를 구축하는 방법을 결정할 수 있도록 합니다.

ComfyUI와 Blender는 외부 선택적 백엔드입니다. 두 백엔드 중 하나가 비활성화, 누락 또는 일시적으로 연결 불가능한 경우 MCP 자체는 정상 상태를 유지합니다. 네트워크 종속 도구는 서버를 중단시키거나 백엔드 부재 도구 오류를 표시하는 대신 모델이 읽을 수 있는 available=false 결과를 반환합니다.

Related MCP server: comfyui-mcp-server-node

아키텍처

MCP client / AI
   |
   |<------ generic MCP file transfer ------>
   v
MCP Video Gen + persistent file_id cache
   |
   |---------------- optional ComfyUI API
   |                    |
   |                    +-- installed models
   |                    +-- custom nodes
   |                    +-- image/video/audio generation
   |
   |---------------- optional Blender bridge on VM
   |                    |
   |                    +-- bpy scene creation/editing
   |                    +-- .blend / GLB export
   |                    +-- still / animation rendering
   |
   |---------------- HyperFrames
   |---------------- OpenTimelineIO / subtitles
   |---------------- scene / frame analysis
   |---------------- whisper.cpp / Silero VAD / RNNoise / aubio
   +---------------- FFmpeg

All execution paths exchange files through the same MCP cache.

Portainer 배포

Stack 정의로 video-mcp.yml을 사용하십시오.

선택적 ComfyUI

일반적인 ComfyUI 연결 변수는 다음과 같습니다:

COMFYUI_HOST=host.docker.internal
COMFYUI_PORT=8188
COMFYUI_SCHEME=http

파일 시스템 검색을 위해 ComfyUI가 존재할 때 호스트 경로를 설정하십시오:

COMFYUI_MODELS_PATH=/host/path/to/ComfyUI/models
COMFYUI_CUSTOM_NODES_PATH=/host/path/to/ComfyUI/custom_nodes

이러한 경로 변수는 더 이상 MCP 시작에 필요하지 않습니다. Stack에는 일반적인 빈 디렉터리 폴백이 있으므로 ComfyUI가 설치되기 전에 시작할 수 있습니다. ComfyUI에 연결할 수 없는 경우 네트워크 도구는 로컬 MCP 도구가 계속 작동하는 동안 해당 상태를 모델에 보고합니다.

선택적 Blender

Blender는 기본적으로 비활성화되어 있습니다:

BLENDER_ENABLED=false
BLENDER_BRIDGE_URL=http://host.docker.internal:9876
BLENDER_BRIDGE_TOKEN=
BLENDER_BRIDGE_TIMEOUT_SEC=7200

권장 통합은 VM에서 직접 전용 낮은 권한 OS 계정으로 scripts/blender_bridge.py를 실행합니다. 컨테이너는 인증된 로컬 HTTP 브리지를 통해 통신합니다. Blender 자체는 호스트에서 헤드리스로 실행됩니다. 이렇게 하면 MCP 컨테이너에 호스트 루트 파일 시스템이나 호스트 실행 파일을 마운트하는 것을 피할 수 있습니다.

브리지가 설치된 후 Portainer에서 개인적으로 구성하십시오:

BLENDER_ENABLED=true
BLENDER_BRIDGE_URL=http://host.docker.internal:9876
BLENDER_BRIDGE_TOKEN=<same long random token used by the host bridge>

설정, 보안, systemd 강화, 파일 흐름 및 예제는 docs/BLENDER_BRIDGE.md 를 참조하십시오.

Cloudflare Tunnel

포함된 Cloudflare Tunnel 사이드카를 사용하는 경우 다음을 제공하십시오:

CLOUDFLARED_TUNNEL_TOKEN=<set privately in Portainer>

원격 Tunnel 호스트 이름을 다음으로 지정하십시오:

http://video-mcp:8000

MCP 엔드포인트는 다음과 같습니다:

https://your-public-host.example/mcp

Cloudflare Access / Managed OAuth

애플리케이션은 원본에서 Cloudflare Access JWT를 확인할 수 있습니다. Portainer에서 이러한 값을 개인적으로 구성하십시오:

CF_ACCESS_VERIFY=true
CF_ACCESS_TEAM_DOMAIN=https://your-team.cloudflareaccess.com
CF_ACCESS_AUD=<Access application audience tag>
PUBLIC_BASE_URL=https://your-public-host.example

실제 도메인, 대상, 터널 토큰, 브리지 토큰, 내부 IP 또는 자격 증명은 이 공개 저장소에 속하지 않습니다.

외부 백엔드 가용성

external_backends_status는 ComfyUI와 Blender의 현재 상태를 보고합니다. inventory_summary는 로컬 기능과 함께 동일한 백엔드 상태를 포함합니다.

외부 백엔드를 사용할 수 없는 경우 호출은 다음과 같은 구조를 반환합니다:

{
  "ok": false,
  "available": false,
  "backend": "blender",
  "status": "unavailable",
  "message": "Blender integration is disabled..."
}

이는 MCP 서버 오류와 의도적으로 다릅니다. 모델은 하나의 선택적 실행 경로를 사용할 수 없음을 학습하고 다른 경로로 계속 진행할 수 있습니다.

파일 전송 및 공유 캐시

생성/가져온 모든 아티팩트는 MCP 캐시로 정규화되고 file_id로 식별됩니다. 이것은 AI 클라이언트, ComfyUI, Blender, FFmpeg, HyperFrames, 자막, 타임라인 및 오디오 유틸리티 간의 상호 교환 계층입니다.

클라이언트 / AI -> MCP

작은 파일의 경우:

cache_text_file
cache_file_base64

더 큰 바이너리 파일의 경우:

file_upload_begin
file_upload_chunk
file_upload_finish
file_upload_abort

청크 업로드는 영구 캐시로 승격되기 전에 예상 바이트 길이와 SHA-256을 지정할 수 있습니다.

MCP -> 클라이언트 / AI

메타데이터:

get_cached_file_info

기존의 작은 호환성 경로:

get_output_inline_base64

제한된 일반 읽기:

read_cached_file_chunk_base64

모든 일반 캐시 메타데이터 객체에는 /files/{file_id}가 포함되며, PUBLIC_BASE_URL이 구성된 경우 완전한 인증된 다운로드 URL도 포함됩니다.

이는 AI가 Blender Python 스크립트를 텍스트로 작성하고, 참조된 임의의 자산을 캐시에 배치하고, 해당 file_id 값을 Blender로 보내고, .blend/.glb/렌더를 새로운 file_id 값으로 받은 다음 해당 파일을 ComfyUI 또는 로컬 후처리 스택에 공급할 수 있음을 의미합니다.

고급 로컬 미디어 유틸리티

런타임은 FFmpeg/HyperFrames 외에도 몇 가지 작은 로컬 유틸리티를 준비합니다. Python venv에는 PySceneDetect, OpenTimelineIO, pysubs2, ONNX Runtime, NumPy 및 헤드리스 OpenCV가 포함되어 있습니다. Debian은 작은 aubio-tools CLI 패키지를 제공합니다. RNNoise와 whisper.cpp는 고정된 업스트림 소스에서 로컬로 빌드되어 영구 데이터 볼륨에 저장됩니다.

Silero VAD, RNNoise 및 whisper.cpp 모델/소스 아티팩트는 영구 데이터 볼륨 아래에 저장됩니다. RNNoise 소스 및 모델과 Silero/Whisper 모델 다운로드는 명시적인 SHA-256 검증을 사용합니다. 기본 Whisper 모델은 가벼운 로컬 전사를 위한 소형 양자화 모델입니다. 모델 URL/해시 및 소스 참조는 Stack 변수를 통해 재정의할 수 있습니다.

관련 변수는 다음과 같습니다:

SILERO_VAD_ENABLED=true
SILERO_VAD_MODEL_URL=<public model URL>
SILERO_VAD_MODEL_SHA256=<expected sha256>

RNNOISE_ENABLED=true
RNNOISE_REF=<pinned upstream commit>
RNNOISE_SOURCE_URL=<public source archive URL>
RNNOISE_SOURCE_SHA256=<expected sha256>
RNNOISE_MODEL_URL=<public model URL>
RNNOISE_MODEL_SHA256=<expected sha256>

WHISPER_CPP_ENABLED=true
WHISPER_CPP_REF=v1.8.6
WHISPER_CPP_BUILD_JOBS=2
WHISPER_MODEL_AUTO_DOWNLOAD=true
WHISPER_MODEL_NAME=tiny-q5_1
WHISPER_MODEL_URL=<public model URL>
WHISPER_MODEL_SHA256=<expected sha256>

이러한 유틸리티를 활성화한 후 첫 번째 시작은 RNNoise와 whisper.cpp가 로컬로 빌드되고 선택한 자산이 다운로드되므로 더 오래 걸릴 수 있습니다. 결과 빌드와 모델은 /data에 남아 있으므로 영구 볼륨이 유지되는 경우 일반 컨테이너 재생성 시 해당 빌드가 반복되지 않습니다. Stack은 이러한 이유로 첫 번째 시작에 확장된 상태 확인 유예 기간을 제공합니다.

선택적 Piper TTS

Piper는 선택적 런타임으로 구현되며 기본적으로 비활성화되어 있습니다:

PIPER_ENABLED=false
PIPER_PACKAGE_SPEC=piper-tts

활성화된 경우 음성이 자동으로 다운로드되지 않습니다. 음성 .onnx 및 일치하는 구성 파일은 /data/piper/voices 아래에 있습니다. piper_import_voice_file로 MCP 미디어 캐시에서 가져올 수 있습니다. 이는 ComfyUI 자체가 오디오/TTS 워크플로우를 호스팅할 수 있기 때문에 TTS를 선택적으로 유지합니다.

타사 라이선스 정보는 THIRD_PARTY.md를 참조하십시오.

릴리스 선택

Stack은 다음을 지원합니다:

VIDEO_MCP_VERSION=latest
VIDEO_MCP_CHECK_UPDATES_ON_START=true
VIDEO_MCP_FORCE_REFRESH=false

latest는 태그가 vX.Y.Z와 정확히 일치하는 가장 높은 비초안, 비시험판 GitHub 릴리스를 의미합니다. main을 의미하지 않습니다.

릴리스를 고정할 수도 있습니다:

VIDEO_MCP_VERSION=v2.4.0

또는 커밋 SHA:

VIDEO_MCP_VERSION=<commit-sha>

업데이트 확인이 비활성화되고 유효한 /current 소스가 존재하는 경우 시작은 완전히 캐시 우선입니다. 실패한 릴리스 조회, 다운로드 또는 아카이브 검증은 마지막으로 알려진 양호한 소스가 있을 때마다 해당 소스로 대체됩니다.

영구 볼륨

Stack은 세 가지 문제를 분리합니다:

video_mcp_code  -> /opt/video-mcp   versioned source cache + /current
video_mcp_venv  -> /opt/venv        persistent Python virtual environment
video_mcp_data  -> /data             media, timelines, models, local tooling, HyperFrames projects/cache

애플리케이션 런타임 데이터 루트는 기본적으로 /data입니다. 직접/비Stack 배포는 VIDEO_MCP_DATA_ROOT로 재정의할 수 있습니다. video_mcp.server 또는 video_mcp.entrypoint를 가져와도 디렉터리가 생성되지 않습니다. 런타임 디렉터리는 애플리케이션이 시작될 때만 생성됩니다.

Python 환경은 requirements.txt가 변경된 경우에만 다시 빌드됩니다. 다시 빌드하면 마운트된 venv 디렉터리의 내용이 지워집니다. Docker 마운트 지점 자체는 절대 제거되지 않습니다.

소스 부트스트랩 보안

소스 아카이브는 GitHub codeload에서 스테이징 디렉터리로 다운로드되어 추출 전에 검증됩니다. 부트스트랩은 다음을 거부합니다:

• 절대 경로;

• .. 탐색;

• 심볼릭 링크;

• 하드 링크;

• 둘 이상의 최상위 루트가 있는 아카이브.

릴리스는 추출 및 런타임 계약 검사가 성공한 후에만 .mcp-source-ready를 받습니다. /current는 그 이후에만 전환되므로 중단되거나 잘못된 업데이트가 마지막으로 알려진 양호한 소스를 대체할 수 없습니다.

ComfyUI 모델 및 사용자 정의 노드 파일 시스템 마운트는 읽기 전용입니다. AI 유틸리티 소스/모델 다운로드는 임시 파일과 SHA-256 검증을 사용하여 캐시된 아티팩트를 교체하기 전에 수행합니다. 선택적 Blender 브리지는 베어러 토큰 인증을 사용하고 선언된 작업 입력/출력만 전송하지만 임의의 Blender Python은 강력하므로 브리지는 권한이 없는 OS 계정으로 격리되어야 합니다.

HyperFrames

HyperFrames는 MCP 컨테이너에서 로컬로 실행되며 MCP 미디어 캐시와 동일한 영구 /data 영역을 사용합니다. 브라우저 자산은 /data/hyperframes-home 아래에 영구적으로 캐시됩니다.

기본 패키지 사양은 재현성을 위해 Stack에 고정되어 있으며 개인적으로 재정의할 수 있습니다:

HYPERFRAMES_NPM_SPEC=hyperframes@0.7.111

HyperFrames 기술은 이 실행 서버에서 의도적으로 비활성화됩니다 (HYPERFRAMES_SKIP_SKILLS=1).

개발

python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt pytest PyYAML
PYTHONPATH=src python -m pytest -q
python scripts/check_public_repo.py

CI는 Python 컴파일, 서버/진입점 가져오기, 테스트, YAML 구문 분석, 셸/Python 도우미 구문, Compose 렌더링, 버전/변경 로그 일관성 및 공개 저장소 비밀/개인 네트워크 가드레일을 확인합니다.

릴리스 프로세스

1. 브랜치에서 개발하고 PR을 엽니다.

2. CI가 통과해야 합니다.

3. VERSION 및 CHANGELOG.md를 업데이트합니다.

4. main에 병합합니다.

5. CI는 아직 존재하지 않는 경우 불변 vX.Y.Z 태그와 일치하는 안정적인 GitHub 릴리스를 생성합니다.

애플리케이션 태그/릴리스는 정확한 vX.Y.Z 이름을 위해 예약되어 있으므로 관련 없는 모델 또는 자산 릴리스가 VIDEO_MCP_VERSION=latest 해상도에 영향을 줄 수 없습니다.

라이선스 및 저작자 표시

Apache License 2.0에 따라 라이선스가 부여됩니다. LICENSE를 참조하십시오.

재배포 및 파생 작업은 Apache License 2.0에 따라 NOTICE의 저작자 표시 고지를 유지해야 합니다. 타사 구성 요소는 자체 라이선스를 유지합니다. THIRD_PARTY.md를 참조하십시오.