LipDub MCP server

让您的 AI 智能体具备视频唇形同步能力。

LipDub 2 能视频中的人物配合另一条音频轨的唇形，看起来像在说那段音频。这是一个 MCP 服务器，可将其开放给 Claude、Cursor、Gemini CLI、Codex、VS Code 以及任何其他兼容 MCP 的客户端。

LipDub 2 不会翻译、转写或生成语音。 音频由您自行提供。如果您想让一个视频配音成另一种语言，请先用文本转语音或语音克隆工具生成该音频，将其托管到公开 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. 打开 设置 → API Keys：app.lipdub.ai/settings/api-keys

   您必须是账户的 Owner（所有者）或 Admin（管理员）。其他角色会被直接重定向到仪表盘，没有任何说明——如果这个链接把您弹回，请让 Owner 或 Admin 为您生成密钥。

3. 生成密钥并复制。

每个用户只有一把密钥。 LipDub 为每个用户发放一把 API 密钥，生成新密钥会替换旧密钥。如果您的账户已将其密钥用于其他集成，生成新密钥会破坏该集成。请复用现有密钥，或者用一个单独的 Owner/Admin 账户来运行 agent。

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. 验证是否正常

让您的 ai 执行：“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 调用，而上传本地文件的路径需要多次调用，并且这些接口每小时限流约十次，也就是说入门套餐大约每小时只能完成两次本地文件渲染。让此服务器只接受 URL，也意味着它在任何位置上运行的行为都是一样的。本地文件支持可能会在之后作为可选项引入。

时间与费用

一次渲染大约需要 7–15 分钟。渲染会消耗您 LipDub 账户中的积分，且无法退款；成本随源视频长度增长，因此越短的片段越划算。

查看渲染状态是免费且不受限流的 —— 您想多久轮询一次都可以。

积分余额无法通过 API 获取；请访问 app.lipdub.ai。

支出防护

lipdub_create_render 是唯一会消费积分的工具。默认它不会执行，直到 agent 传入 confirm_spend，后者会先向您报出成本。服务器还会在每个会话中限制渲染次数（5 次）后停止。

这些是方便安全守卫，而不是安全机制——任何绕过它们直接调用 API 的代码都可以跳过。

故障排除

完整的 API 文档请见：lip.dub.readme.io。

隐私

• 您的 API 密钥从环境中读取，仅用于调用 https://api.lipdub.ai，永远不会写盘、记录日志或出现在工具结果中。每条日志和错误消息都会自动标记或将其从中间移除。

• 您提供的视频和音频 URL 会发送给 LipDub API，API 会下载它们来生成结果。请不要传送您不希望 Lip 处理的内容的 URL。

• 此服务器不发送任何遥测，也没有 token 采集。

• 渲染及产出物会存储在您的 LipDub 账户中，受 Lipub 的隐私政策与条款约束。

可接受的使用

LipDub 2 生成的真实人物的合成视频。使用它即表明您拥有对源素材中影像与声音所须的权利和同意。不要未经本人允许冒充任何人，不要制作误导公众的素材，也不要用于 LipDub 条款禁止的场景。

安全

发现了漏洞？请参考 SECURITY.md。不要公开 issue，也绝不能在 issue 里粘贴 API 密钥。

限制

• 不进行翻译或语音生成——音频由您给出。

• 仅支持 URL 输入，不支持本地文件上传。

• API 无法提供余额与价格估算。

• LipDub 每个账户只有一个 API key，无法仅为本服务限制 key 的权限。

版本策略

API 工具名称是公开契约，不会修改。新能力会以新工具的形式添加，参数变更均为扩展式。参见 CHangelog.md。

许可

MIT。该版权声明覆盖的是本客户端。LipDub 本身是商业服务，以其自己的条款为准。