Remotion 비디오 제작 MCP 서버

AI 에이전트가 오디오 비트를 분석하고, Google Gemini TTS로 음성을 합성하며, Remotion (v4.0+) 및 React를 사용하여 전문적인 비디오를 프로그래밍 방식으로 구축하고 렌더링할 수 있게 해주는 세계적 수준의 Model Context Protocol(MCP) 서버입니다.

두 가지 모두 지원합니다:

• 💻 로컬 STDIO 전송: 로컬 AI 클라이언트(Antigravity, Claude Desktop, Cursor)용.

• 🌐 원격 Streamable HTTP 전송: 클라우드 배포(Render) 및 웹 기반 AI 클라이언트(Claude Web at https://claude.ai/new)용.

🚀 주요 기능

• 🎬 프로그래매틱 스캐폴딩: TikTok/Reels(tiktok-916), YouTube(youtube-169), 소셜(social-11) 등 내장된 화면 비율로 제로 구성 React/Remotion 비디오 프로젝트를 생성합니다.

• 🎙️ Gemini 3.1 Flash TTS 통합: 지역 억양이 포함된 고품질 음성 장면 대사를 생성하고, 키네틱 자막을 위한 단어 단위 타임코드를 생성합니다.

• 🎵 Librosa 오디오 비트 동기화: 배경 음악을 분석하여 BPM, 비트 경계, RMS 에너지 하강/상승을 추출하고 프레임 정확도의 장면 컷을 추천합니다.

• 📸 시각적 미리보기 스냅샷: AI 시각적 검증을 위해 모든 프레임 인덱스에서 프레임 스냅샷(PNG/JPEG/WebP)을 즉시 렌더링합니다.

• ⚡ 헤드리스 렌더링: 멀티코어 동시성 제어 및 진행 상황 추적과 함께 고품질 MP4/WebM 비디오를 프로그래밍 방식으로 컴파일합니다.

• 🔒 Bearer 토큰 인증: 공용 클라우드 서비스에 배포할 때 HTTP MCP 엔드포인트를 보호합니다.

Related MCP server: atsurae

🛠️ 사전 요구 사항

이 MCP 서버를 실행하고 비디오를 렌더링하려면 호스트 환경에 다음이 필요합니다:

1. Node.js(v20.0.0 이상 권장) 및 npm.

2. Python 3(v3.10+ 권장) 및 오디오 패키지 설치:

pip install librosa numpy scipy google-genai

3. Remotion 브라우저 종속성: 헤드리스 Chrome을 실행하려면 Chromium이 필요합니다. CLI를 통해 설치:

npx @remotion/cli browser ensure

🌐 원격 MCP / Claude Web 및 Streamable HTTP 배포

이 서버는 MCP Streamable HTTP 전송 사양(@modelcontextprotocol/sdk v1.29.0)을 지원하므로 Claude Web(https://claude.ai/new)과 같은 웹 기반 클라이언트가 원격으로 연결할 수 있습니다.

1. HTTP 서버를 로컬에서 실행

Streamable HTTP 서버를 빌드하고 시작:

npm install
npm run build
npm run start:http

기본적으로 서버는 다음에서 수신 대기합니다:

• 헬스 체크: GET http://localhost:3000/health

• MCP 엔드포인트: http://localhost:3000/mcp

2. 환경 변수

.env 파일을 생성하거나 환경 변수를 내보냅니다:

3. HTTP MCP 엔드포인트 보안

공용 서버에 배포할 때 MCP_AUTH_TOKEN을 구성합니다:

export MCP_AUTH_TOKEN=your-secret-token-here
npm run start:http

/mcp에 대한 수신 요청에는 다음 헤더가 포함되어야 합니다:

Authorization: Bearer your-secret-token-here

토큰이 없거나 잘못된 토큰이 포함된 요청은 401 Unauthorized 응답을 받습니다.

4. HTTP 및 헬스 엔드포인트 테스트

• 헬스 상태 확인:

curl http://localhost:3000/health
# Response: {"status":"ok","service":"remotion-mcp-server"}

• MCP 초기화 확인:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-token-here" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": { "name": "curl-test", "version": "1.0.0" }
    }
  }'

5. Render에 배포(원클릭 / Blueprint)

저장소에는 Node 20, Chromium, FFmpeg 및 Python 오디오 라이브러리를 패키징하는 render.yaml blueprint와 프로덕션 준비 Dockerfile이 포함되어 있습니다.

1. 저장소를 GitHub에 푸시합니다.

2. Render에 로그인하고 New + -> Blueprint를 클릭합니다.

3. 저장소(remotionMcpServer)를 연결합니다. Render가 render.yaml을 자동으로 감지합니다.

4. Render 대시보드에서 환경 변수를 구성합니다:

   • MCP_AUTH_TOKEN: 사용자 지정 비밀 토큰.

   • GEMINI_API_KEY: Gemini API 키.

5. 배포! 원격 MCP URL은 다음과 같습니다:

https://YOUR-SERVICE-NAME.onrender.com/mcp

6. Claude Web에 연결

1. https://claude.ai/new로 이동합니다.

2. Custom MCP Connectors 설정을 엽니다.

3. 원격 MCP URL을 입력합니다:

https://YOUR-SERVICE-NAME.onrender.com/mcp

4. 인증이 활성화된 경우 Authorization 헤더를 Bearer <your-mcp-auth-token>으로 구성합니다.

5. 저장하고 연결합니다. Claude Web에 5개의 Remotion 도구가 모두 표시됩니다.

💻 로컬 STDIO 설정(Antigravity 및 로컬 클라이언트)

즉시 원커맨드 설정(권장)

터미널에 단일 명령을 복사하여 붙여넣습니다:

🍎 macOS / Linux(터미널)

curl -fsSL https://raw.githubusercontent.com/ivalenzuela/remotion-mcp-server/main/autoinstall.sh | bash

🪟 Windows(PowerShell)

iwr -useb https://raw.githubusercontent.com/ivalenzuela/remotion-mcp-server/main/autoinstall.ps1 | iex

수동 STDIO 구성

1. 서버 컴파일:

git clone https://github.com/ivalenzuela/remotion-mcp-server.git
cd remotion-mcp-server
npm install
npm run build

2. AI 클라이언트에 등록(mcp_config.json / claude_desktop_config.json):

{
  "mcpServers": {
    "remotion": {
      "command": "node",
      "args": ["/path/to/remotion-mcp-server/dist/index.js"],
      "env": {
        "GEMINI_API_KEY": "YOUR_GEMINI_API_KEY_HERE"
      }
    }
  }
}

🤖 사용 가능한 MCP 도구

5개의 도구 모두 STDIO 및 Streamable HTTP 전송에서 동일하게 사용할 수 있습니다:

1. remotion_scaffold_project

사전 구축된 템플릿, 표준 레이아웃 컴포넌트로 완전한 React/Remotion 프로젝트를 스캐폴딩하고 npm 종속성을 자동으로 설치합니다.

• 인수:

  • projectName(문자열, 필수): 대상 프로젝트의 폴더 이름.

  • template(열거형: tiktok-916, youtube-169, social-11, 필수): 화면 비율.

  • targetDir(문자열, 필수): 상위 디렉터리 경로.

2. remotion_analyze_audio

Python Librosa를 사용하여 오디오 파일에 대한 신호 처리를 수행하여 BPM, 비트 프레임, 에너지 프로필, 권장 장면 컷 프레임 번호를 반환하고 SRT 자막을 정렬합니다.

• 인수:

  • audioPath(문자열, 필수): 입력 오디오 트랙 경로.

  • srtPath(문자열, 선택): SRT 자막 파일 경로.

  • outputPath(문자열, 선택): 출력 JSON 분석을 저장할 경로.

  • fps(숫자, 기본값 30): 대상 컴포지션 프레임 속도.

  • minSceneDuration(숫자, 기본값 3.5): 장면 컷 사이의 최소 시간(초).

3. remotion_generate_tts

Google Gemini 3.1 Flash TTS(gemini-3.1-flash-tts-preview)를 사용하여 음성을 합성하고 문자 가중치 단어 타임코드를 출력합니다. GEMINI_API_KEY가 없으면 깨끗한 합성 오디오로 자동 폴백합니다.

• 인수:

  • text(문자열, 필수): 합성할 대화 텍스트.

  • outputPath(문자열, 필수): 생성된 .wav 파일을 저장할 경로.

  • voice(문자열, 기본값 "Puck"): Gemini 사전 구축 음성 이름.

  • accent(문자열, 선택): 선택적 지역 억양 지시.

  • fps(숫자, 기본값 30): 프레임 속도.

4. remotion_preview_frame

Remotion의 CLI를 사용하여 컴포지션의 특정 프레임에 대한 정지 스냅샷 이미지(PNG/JPEG/WebP)를 렌더링합니다.

• 인수:

  • projectDir(문자열, 필수): Remotion 프로젝트 경로.

  • compositionId(문자열, 필수): 대상 Composition ID.

  • frame(숫자, 기본값 0): 캡처할 프레임 인덱스.

  • imageFormat(열거형: png, jpeg, webp, 기본값 png): 형식.

  • props(객체, 선택): 입력 React props.

5. remotion_render_video

컴포지션을 프로덕션급 비디오(MP4/WebM)로 컴파일합니다.

• 인수:

  • projectDir(문자열, 필수): Remotion 프로젝트 경로.

  • compositionId(문자열, 필수): 대상 Composition ID.

  • outputPath(문자열, 선택): 출력 비디오 경로.

  • concurrency(숫자/문자열, 기본값 "auto"): 사용할 CPU 스레드.

  • codec(문자열, 기본값 "h264"): 대상 코덱.

  • props(객체, 선택): 입력 React props.

🎨 사전 구축 React 컴포넌트

스캐폴딩된 프로젝트에는 다음과 같은 프로덕션 준비 레이아웃 컴포넌트가 포함됩니다:

1. SubtitleOverlay: 이중 언어 자막을 위한 단어별 활성 스케일링 및 사용자 지정 텍스트 그림자 글로우("Efecto Lupa PRO").

2. KenBurnsImage: CSS 애니메이션 없이 보간 기반의 깔끔한 이미지 스케일링 및 변환.

3. AudioSpectrum: 사운드트랙에 반응적으로 동기화되는 사운드 주파수 스펙트럼 시각화 막대.

4. LowerThird: 소셜 미디어 프로필 또는 이름 카드를 위한 우아한 하단 서드 팝업.

🧪 테스트 및 검증

도구 실행, 경로 해석 및 CLI 렌더링을 검증하기 위해 전체 E2E 테스트 스위트를 실행합니다:

npm test

📄 라이선스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다.