LipDub MCP server

AI 에이전트가 비디오 립싱크(lip-sync)를 할 수 있게 해 주세요.

LipDub 2는 비디오 속 인물이 다른 오디오 트랙을 말하는 것처럼 보이게 하며, 입 움직임도 일치시킵니다. 이는 이 기능을 Claude, Cursor, Gemini CLI, Codex, VS Code 및 기타 MCP 호환 클라이언트에 노출하는 MCP 서버입니다.

LipDub 2는 번역, 전사, 음성 생성을 하지 않습니다. 오디오는 직접 준비해야 합니다. 비디오를 다른 언어로 더빙하려면 먼저 텍스트 음성 변환(TTS) 또는 음성 복제 도구로 그 오디오를 생성하고, 공개 URL로 호스팅한 뒤 해당 URL을 전달하세요. 이 서버는 TTS 서버와 잘 결합되도록 설계되었습니다. 이것이 의도된 워크플로입니다.

사용 예시

You:   Lip-sync https://example.com/keynote.mp4 to https://example.com/spanish.mp3

Claude: I'll use LipDub 2 for that. This will charge credits to your LipDub
        account and can't be refunded — shall I go ahead?

You:   yes

Claude: Started — render_id rnd_88213. This usually takes 7–15 minutes; I'll wait.
        ...
        Done. Here's your video: https://…  (link expires, so grab it soon)

Related MCP server: atsurae

설정

1. API 키 받기

1. app.lipdub.ai에 로그인합니다.

2. Settings → API Keys를 엽니다. app.lipdub.ai/settings/api-keys

   계정의 Owner(소유자) 또는 Admin(관리자) 여야 합니다. 다른 역할의 사용자는 안내 없이 대시보드로 리다이렉트됩니다. 해당 링크가 그런 식으로 튕겨 버린다면 팀의 Owner 또는 Admin가게 키 생성을 요청하세요.

3. 키를 생성하고 복사합니다.

사용자당 하나의 키. LipDub는 사용자당 API 키를 하나만 발급하며, 새 키를 생성하면 이전 키를 교체합니다. 이미 계정 키를 다른 연동에 사용하고 있다면, 새 키를 생성하면 그 연동이 작동하지 않으니 기존 키를 재사용하거나 에이전트 작업용으로 별도의 Owner/Admin 계정을 사용하세요.

2. 서버 추가하기

아직 npm에 없습니다. 아래의 npx 명령어는 패키지가 게시된 후 작동 방식입니다. 그 전까지는 이 섹션 끝의 소스에서 직접 실행 옵션을 사용하세요. 동일하게 작동합니다.

claude mcp add lipdub --env LIPDUB_API_KEY=your_key_here -- npx -y lipdub-mcp

{
  "mcpServers": {
    "lipdub": {
      "command": "npx",
      "args": ["-y", "lipdub-mcp"],
      "env": { "LIPDUB_API_KEY": "your_key_here" }
    }
  }
}

{
  "mcpServers": {
    "lipdub": {
      "command": "npx",
      "args": ["-y", "lipdub-mcp"],
      "env": { "LIPDUB_API_KEY": "your_key_here" }
    }
  }
}

{
  "inputs": [
    { "type": "promptString", "id": "lipdub-key", "description": "LipDub API Key", "password": true }
  ],
  "servers": {
    "lipdub": {
      "command": "npx",
      "args": ["-y", "lipdub-mcp"],
      "env": { "LIPDUB_API_KEY": "${input:lipdub-key}" }
    }
  }
}

이 방식은 커밋할 수 있는 파일에 키가 들어가지 않게 합니다. LipDub가 사용자당 키를 하나만 발급한다는 점을 고려하면, 대부분의 다른 서버와 달리 이것이 더 중요합니다.

{
  "mcpServers": {
    "lipdub": {
      "command": "npx",
      "args": ["-y", "lipdub-mcp"],
      "env": { "LIPDUB_API_KEY": "your_key_here" }
    }
  }
}

[mcp_servers.lipdub]
command = "npx"
args = ["-y", "lipdub-mcp"]
env = { LIPDUB_API_KEY = "your_key_here" }

git clone https://github.com/marzvfx/lipdub-mcp.git
cd lipdub-mcp
npm ci && npm run build

그런 다음 클라이언트가 빌드된 엔트리 포인트를 가리키게 하세요:

{
  "mcpServers": {
    "lipdub": {
      "command": "node",
      "args": ["/absolute/path/to/lipdub-mcp/dist/index.js"],
      "env": { "LIPDUB_API_KEY": "your_key_here" }
    }
  }
}

Node 20+가 필요합니다. Node를 설치하고 싶지 않다면 ./manage.sh build가 컨테이너 안에서 동일한 작업을 수행합니다.

3. 잘 작동하는지 확인

에이전트에게 "check my LipDub connection" 이라고 물어보세요.

서버를 단독으로도 확인할 수 있습니다:

npx lipdub-mcp --version    # or: node dist/index.js --version

도구

프롬프트를 지원하는 클라이언트에서 슬래시 명령어로 쓸 수 있는 lipdub_quick_dub 프롬프트와, 참조 리소스인 lipdub://guide/quickstart 및 lipdub://guide/troubleshooting도 있습니다.

좋은 소스 비디오란

• 카메라 한 인물이 있어야 합니다.

• 얼굴이 선명하게 보이고 조명이 잘 들어와야 합니다.

• 비디오: .mp4, .mov, .avi, .webm. 오디오: .mp3, .wav, .m4a, .aac.

파일 호스팅

두 입력 모두 공개 URL이며 로컬 파일 경로가 아닙니다. 링크는 미디어 파일 자체를 반환해야 합니다.

다음은 작동하지 않습니다: Google Drive, Dropbox 및 YouTube의 공유 페이지; 로그인이 필요한 모든 것; 만료된 링크.

작동하는 것:

# Amazon S3 — a time-limited direct link
aws s3 presign s3://your-bucket/keynote.mp4 --expires-in 3600

# Google Cloud Storage
gcloud storage sign-url gs://your-bucket/keynote.mp4 --duration=1h

# Any web server
scp keynote.mp4 you@yourserver:/var/www/html/
# → https://yourserver/keynote.mp4

왜 로컬 파일이 아니라 URL인가요? URL 기반 렌더는 API 호출 한 번이면 됩니다. 로컬 파일을 업로드하는 방식은 시간당 약 열 번으로 제한되는 엔드포인트를 여러 번 호출해야 하며, 이는 엔트리 요금제에서 시간당 로컬 파일 렌더 약 2개에 해당합니다. 이 서버가 URL 전용이라는 것은 또한 서버가 어디에서 실행되든 동일하게 동작한다는 뜻입니다. 로컬 파일 지원은 나중에 옵트인(opt-in) 방식으로 추가될 수 있습니다.

소요 시간 및 비용

렌더는 약 7~15분이 걸립니다. 렌더는 LipDub 계정의 크레딧을 소모하며 환불되지 않습니다. 비용은 소스 비디오의 길이에 비례하므로 짧은 클립이 더 저렴합니다.

상태 확인은 무료이고 요청 제한도 없습니다 — 원하는 만큼 자주 폴링하세요.

크레딧 잔액은 API로 확인할 수 없습니다. app.lipdub.ai에서 확인하세요.

지출 보호 장치

lipdub_create_render가 비용을 발생시키는 유일한 도구입니다. 기본적으로 에이전트가 confirm_spend 파라미터를 전달할 때까지 실행을 거부하며, 해당 파라미터는 에이전트가 먼저 대가를 사용자에게 명시하도록 강제합니다. 서버는 세션당 5회 렌더 후에 중단됩니다.

이 설정은 보안 기능이 아니라 사용 편의를 위한 안전장치입니다. 어떤 방식으로든 API를 직접 호출하면 이를 우회할 수 있습니다.

문제 해결

전체 API 문서: lipdub.readme.io

개인정보 보호

• 당신의 API 키는 환경에서 읽히고 https://api.lipdub.ai만 호출하는 데 사용되며, 디스크에 기록하거나 로그에 남기거나 어떤 도구 결과에도 포함되지 않습니다. 모든 로그 줄과 오류 메시지에서 마스킹 처리됩니다.

• 제공한 비디오 및 오디오 URL은 LipDub API로 전송되어 이 URLs가 파일을 받아 렌더를 만듭니다. LipDub가 처리를 원하지 않는 자료의 URL은 전달하지 마세요.

• 이 서버는 텔레메트리 생성, 분석 데이터를 수집하지 않습니다.

• 렌더와 산출 결과물은 Lip Dub 계정에 저장되며, Lip구독의 개인정보 정책 및 약관이 적용됩니다.

허용 용도

LipBud 2는 실제 사람의 합성 영상을 생성합니다. 프로젝트 사용하면, 소스 자료의 초상화과 음성 사용에 필요한 권위와 동의를 보유하고 있음을 보증하게 됩니다. 허락 없인 어떤 사람을 사칭하거나, 실제 인물에 대한 오해를 어필하는 콘텐츠를 만들거나, LipDub의 이용약관이 금지하는 어떤 행위로도 사용하지 마세요.

보안

취약점을 발견했다면 SECURITY.md를 참조하세요. 공개적으로 issue를 열지 말고, API 키를 절대 이슈에 붙여넣지 마세요.

제한사항

• 번역 및 음성 생성 없음 — 오디오는 직접 제공해야 합니다.

• URL 입력만 가능; 로컬 파일 업로드 번호.

• API에서 크레딧 잔액과 가격 예상 정보는 제공되지 않습니다.

• Lip구독은 각 사용자의 하나의 인증 키만 발급하므로, 이 서버 전용으로 키를 한정할 수 없습니다.

버전 관리

도앱 이름은 공개된 계약이며 변경되지 않습니다. 새로운 기능은 새 도구로 추가됩니다. Schema 변경은 추가 방식입니다. CHANGELOG.md를 참조하세요.

라이선스

MIT. 이 라이선스는 이 클라이언트에 해당합니다. 이 자체는 자체 약관의 적용을 받는 상용 서비스입니다.