videolab-mcp

Claude(또는 모든 MCP 호스트)를 숏폼 비디오를 위한 실무형 비디오 편집기로 바꿔주는 MCP 서버입니다. 음악 라이브러리를 탐색하거나 새로운 트랙을 생성하세요. Veo로 스틸 이미지를 애니메이션화하거나 OmniHuman으로 인물 영상의 립싱크를 맞출 수 있습니다. 스크립트를 작성하고 수정하세요. ElevenLabs로 보이스오버를 합성하세요. FFmpeg로 타임라인을 구성하고, 결과물을 재생한 뒤, 음악이나 보이스오버, 또는 특정 클립 하나만 교체하여 처음부터 다시 렌더링할 필요 없이 저렴한 비용으로 반복 작업(iterate)을 수행하세요.

또한 긴 텍스트(PDF, 도서, 논문)를 AI가 생성한 보이스오버, 자막, B-roll이 포함된 구조화된 다큐멘터리 영상으로 변환하는 텍스트-투-다큐멘터리(text-to-documentary) 기술도 제공합니다.

독립형이며, 이식성이 좋고, 설정이 가능합니다. 본인의 API 키를 사용하세요.

포함된 기능

워크플로우 전반에 걸친 도구:

도구 호출 없이 탐색하기 위한 리소스: library://music, library://broll, library://renders, library://voiceovers, library://scripts, library://scenes.

단계별 가이드 흐름을 위한 프롬프트: make-scene-promo, remix-render, compose-music-for-scene.

skills/ 내의 기술: text-to-documentary — PDF/도서 → 챕터별 구조화된 서사 구조를 가진 다큐멘터리 영상.

Related MCP server: Video MCP

요구 사항

• Node.js 18 이상

• PATH에 FFmpeg 설치 (또는 설정에서 ffmpeg.binary를 절대 경로로 지정)

• 사용하는 제공업체의 API 키 (사전 필수 사항 없음 — 첫 호출 시 지연 초기화)

퀵스타트

git clone <this-repo> videolab-mcp
cd videolab-mcp
npm install
npm run build
cp videolab.config.example.json videolab.config.json
cp .env.example .env  # then fill in keys you have

Claude Desktop에 연결하세요 (macOS의 경우 ~/Library/Application Support/Claude/claude_desktop_config.json, Windows의 경우 %AppData%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "videolab": {
      "command": "node",
      "args": ["C:\\path\\to\\videolab-mcp\\build\\index.js"],
      "env": {
        "ELEVENLABS_API_KEY": "...",
        "ANTHROPIC_API_KEY": "...",
        "GOOGLE_VEO_API_KEY": "...",
        "FAL_KEY": "...",
        "VIDEOLAB_CONFIG": "C:\\path\\to\\videolab-mcp\\videolab.config.json"
      }
    }
  }
}

Claude Desktop을 재시작하세요. 채팅을 열고 ping을 호출하여 연결을 확인하세요.

설정

두 개의 파일이 필요합니다. 보안 정보 전용 .env:

ELEVENLABS_API_KEY=
ANTHROPIC_API_KEY=
GOOGLE_VEO_API_KEY=
FAL_KEY=

그 외 모든 설정(스토리지, 제공업체, FFmpeg 플래그, 기본값)은 videolab.config.json에서 관리합니다. 예시 파일은 로컬 스토리지, JSON 인덱스, ElevenLabs/Anthropic/Veo/Fal 제공업체, 모바일(9:16) 기본값 등 합리적인 설정을 포함하고 있습니다.

워크스루 — 처음부터 프로모션 영상 만들기

Claude Desktop에서 MCP 서버가 연결된 상태로:

User: Make a 20-second mobile promo for the test scene.

Claude:
  → list_scene_assets({ sceneRef: { key: "test-scene" } })
     → 3 assets: magenta, cyan, orange

  → generate_script({
      context: "Test scene with three coloured backdrops",
      durationSeconds: 20, tone: "punchy"
    })
     → scriptId: script_a3f, slot breakdown shown

  → generate_voiceover({ text: "<the script>" })
     → voiceoverId: vo_8d2

  → generate_music({
      prompt: "driving electronic, slow build, retro synth pad",
      durationMs: 20000
    })
     → trackId: music_4e1

  → assemble_promo({
      timeline: {
        platform: "mobile",
        slots: [
          { source: { kind: "scene", id: "asset-test-magenta" }, durationMs: 7000 },
          { source: { kind: "scene", id: "asset-test-cyan" },    durationMs: 7000 },
          { source: { kind: "scene", id: "asset-test-orange" },  durationMs: 6000 }
        ]
      },
      voiceoverId: "vo_8d2",
      musicId: "music_4e1"
    })
     → renderId: render_94c, autoplays in default video player

User: Make the music more chill.

Claude:
  → generate_music({ prompt: "soft ambient pad, gentle rhythm", durationMs: 20000 })
     → trackId: music_c70
  → swap_music({ renderId: "render_94c", newMusicId: "music_c70" })
     → renderId: render_d11 (rev of render_94c) — only re-mixes audio (~2s)

User: Replace the orange shot with a Veo animation of the magenta image zooming in.

Claude:
  → animate_image_to_video({
      imageSource: { kind: "scene", id: "asset-test-magenta" },
      prompt: "slow camera push-in, dust particles drifting"
    })
     → clipId: broll_veo_a8b
  → swap_clip({
      renderId: "render_d11",
      slotIndex: 2,
      newSource: { kind: "broll", id: "broll_veo_a8b" }
    })
     → renderId: render_2f9 (rev of render_d11)

반복 루프

워크플로우를 효율적으로 만드는 핵심 요소입니다:

• **assemble_promo**는 슬롯별 중간 파일(slot_*.mp4), 무음 visuals.mp4, 오디오 믹스, 최종 output.mp4를 모두 media/renders/<renderId>/ 아래에 생성합니다.

• swap_music / **swap_voiceover**는 부모의 visuals.mp4를 재사용하고 오디오만 다시 믹싱합니다. 일반적인 소요 시간: 약 2초.

• **swap_clip**은 비주얼 스트림을 다시 빌드하고 오디오를 다시 믹싱합니다. 일반적인 소요 시간: 약 5~10초.

• 모든 렌더링은 parentId로 연결된 새로운 renderId를 가지므로 이전 버전을 잃어버릴 염려가 없습니다.

텍스트-투-다큐멘터리 모드

skills/text-to-documentary/ 기술은 PDF, 도서 또는 붙여넣은 긴 텍스트를 챕터당 약 5분 분량의 다큐멘터리 영상 시리즈로 변환합니다. 각 영상은 구조화된 서사 구조(후크 → 핵심 아이디어 → 예시 → 패턴 인터럽트 → 요약 → 클리프행어), ElevenLabs 정렬 타임스탬프를 사용한 노래방 스타일 자막, AI 생성 B-roll을 포함합니다.

사용 도구: extract_pdf, split_chapters, plan_documentary_scenes, validate_attention, generate_voiceover, generate_image, animate_image_to_video, generate_music, assemble_promo.

Claude Code나 기술을 지원하는 다른 호스트를 사용하는 경우, 트리거가 발생하면(예: "이 PDF를 다큐멘터리로 만들어줘", "이 책으로 영상을 만들어줘" 등) 기술이 자동으로 로드됩니다. 그렇지 않은 경우 skills/text-to-documentary/SKILL.md를 읽고 도구를 직접 호출하세요.

사용자 정의 장면 에셋 제공업체

이 서버는 장면 에셋에 대해 제공업체 독립적입니다. 기본 제공되는 json-manifest 제공업체는 JSON 파일에서 읽어옵니다. 더 복잡한 구현(CMS, 데이터베이스, API 등)은 SceneAssetProvider로 구현할 수 있습니다:

export interface SceneAssetProvider {
  readonly kind: string;
  describeRefShape(): string;  // shows up in the tool description so the host knows what to send
  listAssets(ref: SceneRef): Promise<SceneAsset[]>;
  getAsset(id: string): Promise<SceneAsset | null>;
}

구현 내용을 src/providers/scene-assets/<your-name>.ts에 넣고, src/providers/factory.ts의 buildSceneAssets에 등록한 뒤, src/config.ts의 설정 스키마에 추가하세요. 동일한 패턴이 스토리지 백엔드(S3, Azure)에도 적용됩니다 — src/providers/types.ts:StorageProvider를 참조하세요.

제공업체 매트릭스

환경 변수를 통한 선택적 모델 재정의: ANTHROPIC_MODEL, ELEVENLABS_MUSIC_MODEL, VEO_MODEL, VEO_ENDPOINT, VEO_POLL_INTERVAL_MS, VEO_POLL_TIMEOUT_MS, FAL_OMNIHUMAN_MODEL, PROMO_VIDEO_LOG_LEVEL.

라이선스

MIT — LICENSE를 참조하세요.