orcadub-mcp-server

---

让任何支持 MCP 的 Agent——Claude Code、Claude Desktop、Codex CLI、Cursor、Windsurf——都能将视频配成其他语言：上传文件或传入 URL，通过 OrcaRouter 网关向 orca/dub 模型提交任务、轮询进度，并下载完成后的 MP4。

CLI 用法

每项操作都是一次性子命令（无需常驻服务）：

export ORCADUB_API_KEY=sk-orca-...   # from https://www.orcarouter.ai/console

npx -y @orcadub/cli health
npx -y @orcadub/cli upload --path ./clip.mp4
npx -y @orcadub/cli create --source-lang en --target-lang ja \
  --url https://youtu.be/... --opt preserve_bgm=true
npx -y @orcadub/cli get --video-id <id>
npx -y @orcadub/cli download --video-id <id> --dest ./out.mp4

可选的 create 参数使用可重复的 --opt key=val（例如： --opt watermark=false --opt resolution=1080p --opt glossary.OrcaDub=OrcaDub）。 结果以 JSON 格式输出到标准输出；错误输出到标准错误，并以非零状态码退出。

不指定子命令时，同一二进制文件会作为 MCP stdio 服务运行（npx -y @orcadub/cli）。

安装 Agent Skill

dub-video Skill 会教 Agent 何时进行配音、必须确认哪些计费参数，以及如何执行上传 → 创建 → 轮询 → 下载的工作流。通过交互方式安装：

npx -y @orcadub/cli skill install

引导式安装程序会先显示一个均衡的 8 行 ORCADUB 字标，随后你可以：

• 选择简体中文或英文界面；系统区域设置会决定初始默认语言。
• 使用方向键选择 Project 或 Global 安装。
• 从复选框列表中选择一个或多个平台。检测到的平台会显示在最前面，并默认勾选。
• 按 Space 切换，按 / 筛选，按 a 全选，按 n 清空所有选择，按 Enter 确认。

它支持 36 个平台：33 个平台的 Comet 兼容目录，以及 Hermes、OpenClaw 和 Command Code。使用 --lang zh 或 --lang en 跳过语言选择界面。对于无人值守或由 Agent 驱动的设置，请明确选择目标平台：

# Current project
npx -y @orcadub/cli skill install \
  --platform claude --platform codex --scope project --lang en --yes

# User-wide Codex installation
npx -y @orcadub/cli skill install \
  --platform codex --scope global --lang zh --yes

使用 --yes 接受检测到的平台（若未检测到任何平台，则接受所有平台），而不打开安装程序。使用 --json 输出不含装饰的结构化内容。设置 NO_COLOR（或使用 TERM=dumb）可禁用安装程序的颜色。已有的相同内容会保持不变；除非提供 --force，否则已有的不同 Skill 会保留。安装 Skill 需要访问网络以连接规范的 orcadub-plugin 仓库，但无需设置 ORCADUB_API_KEY，也不会连接 OrcaRouter。

快速开始

claude mcp add orcadub -e ORCADUB_API_KEY=sk-orca-... -- npx -y @orcadub/cli

然后直接向你的 Agent 提问：“把这个视频配成中文：https://www.youtube.com/watch?v=…”

前提条件

必须提供 OrcaRouter API 密钥——每次工具调用都需要进行身份验证：

1. 在 OrcaRouter 控制台注册或登录。
2. 在令牌管理页面创建 API 密钥（格式类似 sk-orca-...）。
3. 通过 ORCADUB_API_KEY 环境变量提供该密钥（见下文）。

配音任务按源视频分钟数计费。未提供密钥时，服务仍会启动，但每次工具调用都会返回指向控制台的注册引导链接。

安装

Claude Code

claude mcp add orcadub -e ORCADUB_API_KEY=sk-orca-... -- npx -y @orcadub/cli

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "orcadub": {
      "command": "npx",
      "args": ["-y", "@orcadub/cli"],
      "env": { "ORCADUB_API_KEY": "sk-orca-..." }
    }
  }
}

Codex CLI

codex mcp add orcadub --env ORCADUB_API_KEY=sk-orca-... -- npx -y @orcadub/cli

Cursor / Windsurf / 其他 MCP 主机

任何可启动 stdio MCP 服务的主机都适用相同的配置形式：命令为 npx，参数为 ["-y", "@orcadub/cli"]，环境变量为 ORCADUB_API_KEY。Claude Code、Codex、Cursor 和 Windsurf 的可直接复制配置文件位于 examples/。

Docker

镜像已发布到 GHCR，支持 linux/amd64 和 linux/arm64：

docker pull ghcr.io/continuum-ai-corp/orcadub-mcp-server:latest
claude mcp add orcadub -e ORCADUB_API_KEY=sk-orca-... -- \
  docker run --rm -i -e ORCADUB_API_KEY -v "$PWD:$PWD" -w "$PWD" \
  ghcr.io/continuum-ai-corp/orcadub-mcp-server:latest

或者使用主机 JSON 配置：

{
  "mcpServers": {
    "orcadub": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "ORCADUB_API_KEY",
               "-v", "/path/to/videos:/work", "-w", "/work",
               "ghcr.io/continuum-ai-corp/orcadub-mcp-server:latest"],
      "env": { "ORCADUB_API_KEY": "sk-orca-..." }
    }
  }
}

注意：dub_upload 和 dub_download 会读写本地路径，因此请挂载用于上传或下载的目录（使用 -v 标志）——传递给工具的路径必须在容器内有效。

预构建二进制文件

从发布页面下载适用于你平台的二进制文件（使用 checksums.txt 验证），然后直接注册：

# example: Linux amd64 via gh CLI
gh release download v0.1.0 -R Continuum-AI-Corp/orcadub-mcp-server \
  -p 'orcadub-mcp-server_*_linux_amd64' -O ~/bin/orcadub-mcp-server && chmod +x ~/bin/orcadub-mcp-server
claude mcp add orcadub -e ORCADUB_API_KEY=sk-orca-... -- ~/bin/orcadub-mcp-server

从源代码构建

git clone https://github.com/Continuum-AI-Corp/orcadub-mcp-server && cd orcadub-mcp-server && make build
# binary lands in bin/orcadub-mcp-server

配置

环境变量	必需	说明
ORCADUB_API_KEY	是	OrcaRouter sk-orca-... 密钥，每次请求都会通过 Authorization: Bearer 发送。网关会据此解析你的工作区和账单。

网关地址（https://api.orcarouter.ai）已固定在二进制文件中，无需进行其他配置。

工具

工具	说明
dub_health	端到端探测网关 → orca/dub 路由。不创建任务，也不会产生费用。
dub_upload	上传本地视频文件；返回供 dub_create 使用的 file_id。超过 64 MiB 的文件会自动分块（最大 8 GiB）。
dub_create	提交配音任务（计费）。来源必须且只能是 file_id 或 url 之一（YouTube 和直接链接会由服务端获取）。必需参数：source_lang、target_lang（不能为 auto），以及使用 file_id 时的 video_name。可选参数包括内容配置、术语表、翻译风格、保留背景音乐、口型同步、水印、分辨率／比例等。
dub_get	轮询任务状态：queued → in_progress → completed | failed，并显示整数进度。任务完成后，响应会包含 content_url（通过 Bearer 验证的下载地址，永不过期）和 job_id。
dub_download	将已完成任务的 MP4 保存到本地路径（若文件已存在则拒绝覆盖）。

支持的语言：en zh ja ko fr de es pt ru ar it hi tr th vi id bn pl nl uk fil el cs sv da no fi sk。

示例

典型的 Agent 对话：

用户： 把这个配成中文：https://www.youtube.com/watch?v=xxxx

Agent： (使用 source_lang=en、target_lang=zh、url=… 调用 dub_create) → 任务已排队 → (每隔约 30 秒轮询 dub_get) → 已完成 → (询问是否下载到本地；默认当前目录) → (调用 dub_download) → “已保存到 ./My-Video-zh.mp4 — 可随时重新下载：curl -H "Authorization: Bearer sk-orca-..." <content_url> -o out.mp4”

也可以直接在 Agent 提示词中调用工具，例如 dub_create {"source_lang":"en","target_lang":"zh","url":"https://…","glossary":{"OrcaRT":"OrcaDub Realtime"}}。

故障排除

现象	原因／解决方法
工具调用返回 not authorized … www.orcarouter.ai/console	未设置 ORCADUB_API_KEY——注册、导出密钥并重启会话。
401	密钥无效或已过期——在 OrcaRouter 控制台重新签发。
402 insufficient_credit	为 OrcaRouter 账户充值（按分钟计费）。
429 free_quota_exceeded	已达到免费额度上限。
dub_get 返回 task_not_exist	此 ID 并非通过该网关创建——请使用 dub_create 返回的原始 ID。

开发

go build ./...
go test ./... -count=1

目录结构：cmd/（入口点） · internal/（HTTP 客户端、Skill 安装器、工具层、线协议类型） · npm/（从 GitHub Releases 下载平台二进制文件的 npx 启动器） · server.json（MCP Registry 清单）。

发布

1. 打标签：git tag v0.1.0 && git push origin v0.1.0。
2. GitHub Actions 运行 goreleaser：linux/darwin/windows × amd64/arm64 二进制文件、归档文件和校验和会上传到 Release。
3. npm-publish 作业会将标签版本写入 npm/package.json，并将 @orcadub/cli 发布到 npm（需要仓库密钥 NPM_TOKEN）。
4. registry 作业会将相同的标签版本写入 server.json，并将其发布到 MCP Registry。

许可证

MIT