内容
<div align="center">
<img src="assets/orcadub.png" alt="OrcaDub" width="340">
### 翻译任何视频。保留原声。
**官方 [MCP](https://modelcontextprotocol.io) 服务器，用于 [OrcaDub](https://orcadub.orcarouter.ai) — 由您的代理驱动的 AI 视频配音。**
[](https://github.com/Continuum-AI-Corp/orcadub-mcp-server/actions/workflows/ci.yml)
[](https://github.com/Continuum-AI-Corp/orcadub-mcp-server/releases)
[](https://www.npmjs.com/package/@orcadub/mcp)
[](LICENSE)
[网站](https://orcadub.orcarouter.ai) · [API 文档](https://orcadub.orcarouter.ai/api-docs) · [获取 API 密钥](https://www.orcarouter.ai/console) · [配置示例](examples/) · [版本发布](https://github.com/Continuum-AI-Corp/orcadub-mcp-server/releases)
</div>
---
赋予任何支持 MCP 的代理 — Claude Code、Claude Desktop、Codex CLI、Cursor、Windsurf — 将视频配音成另一种语言的能力：上传文件或传递 URL，通过 [OrcaRouter](https://www.orcarouter.ai) 网关将作业提交给 `orca/dub` 模型，轮询进度，并下载完成的 MP4。
## 快速开始
```bash
claude mcp add orcadub -e ORCADUB_API_KEY=sk-orca-... -- npx -y @orcadub/mcp
```
然后只需询问您的代理： *"将此视频配音成中文：https://www.youtube.com/watch?v=…"*
## 先决条件
**OrcaRouter API 密钥** 是必需的 — 每次工具调用都需要身份验证：
1. 在 [OrcaRouter 控制台](https://www.orcarouter.ai/console) 注册/登录。
2. 在令牌管理页面创建 API 密钥（类似于 `sk-orca-...`）。
3. 通过 `ORCADUB_API_KEY` 环境变量提供它（参见下文）。
配音作业按源视频每分钟计费。没有密钥，服务器仍会启动，但每次工具调用都会返回一个注册重定向到控制台。
## 安装
### Claude Code
```bash
claude mcp add orcadub -e ORCADUB_API_KEY=sk-orca-... -- npx -y @orcadub/mcp
```
### Claude Desktop
添加到 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"orcadub": {
"command": "npx",
"args": ["-y", "@orcadub/mcp"],
"env": { "ORCADUB_API_KEY": "sk-orca-..." }
}
}
}
```
### Codex CLI
```bash
codex mcp add orcadub --env ORCADUB_API_KEY=sk-orca-... -- npx -y @orcadub/mcp
```
### Cursor / Windsurf / 其他 MCP 主机
任何启动 stdio MCP 服务器的主机都适用于相同的形状：命令 `npx`，参数 `["-y", "@orcadub/mcp"]`，环境变量 `ORCADUB_API_KEY`。Claude Code、Codex、Cursor 和 Windsurf 的即用配置位于 [`examples/`](examples/) 中。
### Docker
镜像发布到 GHCR，适用于 linux/amd64 和 linux/arm64：
```bash
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 配置：
```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` 标志）— 您传递给工具的路径必须在容器内有效。
### 预编译二进制文件
从 [发布页面](https://github.com/Continuum-AI-Corp/orcadub-mcp-server/releases) 下载适用于您平台的二进制文件（使用 `checksums.txt` 进行验证），然后直接注册：
```bash
# 示例：通过 gh CLI 下载 Linux amd64
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
```
### 从源代码编译
```bash
git clone https://github.com/Continuum-AI-Corp/orcadub-mcp-server && cd orcadub-mcp-server && make build
# 二进制文件位于 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`）和 `video_name`（使用 `file_id` 时）。可选旋钮涵盖内容配置文件、词汇表、翻译样式、背景音乐保留、唇同步、水印、分辨率/比例等。 |
| `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`。
## 示例
与代理的典型对话：
> **用户：** 将此视频配音成中文：https://www.youtube.com/watch?v=xxxx
>
> **代理：** *(dub_create with source_lang=en, target_lang=zh, url=…)* → 作业排队 → *(每 30 秒轮询 dub_get)* → 已完成 → *(询问：是否下载到本地？默认：当前目录)* → *(dub_download)* → "保存到 ./My-Video-zh.mp4 — 随时可重新下载：`curl -H "Authorization: Bearer sk-orca-..." <content_url> -o out.mp4`"
直接从代理提示符使用工具也适用 — 例如 `dub_create {"source_lang":"en","target_lang":"zh","url":"https://…","glossary":{"OrcaRT":"鲸鸣实时"}}`。
## 故障排除
| 症状 | 原因/解决方法 |
|---|---|
| 工具调用返回 `not authorized … www.orcarouter.ai/console` | `ORCADUB_API_KEY` 未设置 — 注册，导出密钥，重启会话。 |
| `401` | 无效或过期的密钥 — 在 OrcaRouter 控制台重新颁发。 |
| `402 insufficient_credit` | 充值您的 OrcaRouter 余额（每分钟计费）。 |
| `429 free_quota_exceeded` | 免费额度已达上限。 |
| `task_not_exist` on `dub_get` | 该 ID 不是通过此网关创建的 — 使用 `dub_create` 返回的 ID。 |
## 开发
```bash
go build ./...
go test ./... -count=1
```
布局：`cmd/`（入口点）· `internal/`（HTTP 客户端，工具层，线路类型）· `npm/`（npx 启动器，从 GitHub Releases 下载平台二进制文件）· `server.json`（MCP 注册表清单）。
## 发布
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-mcp-server` 发布到 npm（需要存储库秘密 `NPM_TOKEN`）。
4. 可选地，使用 `mcp-publisher publish` 将 `server.json` 发布到 [MCP 注册表](https://registry.modelcontextprotocol.io)。
## 许可证
[MIT](LICENSE)
