Give any MCP-capable agent — Claude Code, Claude Desktop, Codex CLI, Cursor, Windsurf — the ability to dub a video into another language: upload a file or pass a URL, submit a job to the orca/dub model through the OrcaRouter gateway, poll progress, and download the finished MP4.
Quick start
claude mcp add orcadub -e ORCADUB_API_KEY=sk-orca-... -- npx -y @orcadub/mcp
Then just ask your agent: "Dub this into Chinese: https://www.youtube.com/watch?v=…"
Prerequisites
An OrcaRouter API key is required — every tool call is authenticated:
- Register / log in at the OrcaRouter console.
- Create an API key on the token management page (it looks like
sk-orca-...).
- Provide it via the
ORCADUB_API_KEY environment variable (see below).
Dubbing jobs are billed per minute of source video. Without a key the server still starts, but every tool call returns a sign-up redirect to the console.
Installation
Claude Code
claude mcp add orcadub -e ORCADUB_API_KEY=sk-orca-... -- npx -y @orcadub/mcp
Claude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"orcadub": {
"command": "npx",
"args": ["-y", "@orcadub/mcp"],
"env": { "ORCADUB_API_KEY": "sk-orca-..." }
}
}
}
Codex CLI
codex mcp add orcadub --env ORCADUB_API_KEY=sk-orca-... -- npx -y @orcadub/mcp
Cursor / Windsurf / other MCP hosts
Any host that launches stdio MCP servers works with the same shape: command npx, args ["-y", "@orcadub/mcp"], env ORCADUB_API_KEY. Ready-to-copy configuration files for Claude Code, Codex, Cursor and Windsurf live in examples/.
Docker
Images are published to GHCR for linux/amd64 and 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
Or as host JSON config:
{
"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-..." }
}
}
}
Note: dub_upload and dub_download read/write local paths, so mount the
directory you upload from / download to (the -v flag) — paths you pass to
the tools must be valid inside the container.
Prebuilt binaries
Download the binary for your platform from the
releases page
(verify with checksums.txt), then register it directly:
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
From source
git clone https://github.com/Continuum-AI-Corp/orcadub-mcp-server && cd orcadub-mcp-server && make build
Configuration
| Environment variable | Required | Description |
|---|
ORCADUB_API_KEY | yes | OrcaRouter sk-orca-... key, sent as Authorization: Bearer on every request. The gateway resolves your workspace and billing from it. |
The gateway address (https://api.orcarouter.ai) is fixed in the binary — there is nothing else to configure.
| Tool | Description |
|---|
dub_health | End-to-end probe of gateway → orca/dub routing. No job is created, nothing is billed. |
dub_upload | Upload a local video file; returns the file_id for dub_create. Files above 64 MiB are chunked automatically (up to 8 GiB). |
dub_create | Submit a dubbing job (billed). Source is exactly one of file_id or url (YouTube and direct links are fetched server-side). Required: source_lang, target_lang (never auto), and video_name when using file_id. Optional knobs cover content profiles, glossaries, translation style, background-music preservation, lipsync, watermarking, resolution/ratio and more. |
dub_get | Poll a job: queued → in_progress → completed | failed with integer progress. On completion the response includes content_url (Bearer-authenticated delivery address, never expires) and job_id. |
dub_download | Save a completed job's MP4 to a local path (refuses to overwrite existing files). |
Supported languages: 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.
Example
A typical agent conversation:
User: Dub this into Chinese: https://www.youtube.com/watch?v=xxxx
Agent: (dub_create with source_lang=en, target_lang=zh, url=…) → job queued → (polls dub_get every ~30 s) → completed → (asks: download locally? default: current directory) → (dub_download) → "Saved to ./My-Video-zh.mp4 — re-download any time: curl -H "Authorization: Bearer sk-orca-..." <content_url> -o out.mp4"
Direct tool usage from an agent prompt works too — for example dub_create {"source_lang":"en","target_lang":"zh","url":"https://…","glossary":{"OrcaRT":"鲸鸣实时"}}.
Troubleshooting
| Symptom | Cause / fix |
|---|
Tool calls return not authorized … www.orcarouter.ai/console | ORCADUB_API_KEY is unset — register, export the key, restart the session. |
401 | Invalid or expired key — re-issue on the OrcaRouter console. |
402 insufficient_credit | Top up your OrcaRouter balance (per-minute billing). |
429 free_quota_exceeded | Free-tier limit reached. |
task_not_exist on dub_get | The id wasn't created through this gateway — use the id exactly as returned by dub_create. |
Development
go build ./...
go test ./... -count=1
Layout: cmd/ (entrypoint) · internal/ (HTTP client, tool layer, wire types) · npm/ (npx launcher that downloads the platform binary from GitHub Releases) · server.json (MCP Registry manifest).
Releasing
- Tag:
git tag v0.1.0 && git push origin v0.1.0.
- GitHub Actions runs goreleaser: linux/darwin/windows × amd64/arm64 binaries + archives + checksums land on the Release.
- The
npm-publish job stamps the tag version into npm/package.json and publishes orcadub-mcp-server to npm (requires the NPM_TOKEN repo secret).
- Optionally publish
server.json to the MCP Registry with mcp-publisher publish.
License
MIT
