seedance-2-mcp
seedance-2-mcp
Un servidor MCP (Model Context Protocol) de código abierto y ejecución local que expone las capacidades de generación de video de Seedance 2.0 de Volcengine ARK a través de tres herramientas stdio para cualquier cliente MCP como Codex, Claude Desktop, Cursor, etc.
stdio puramente local, no requiere despliegue en la nube.
Desarrollado con Node.js + TypeScript, utilizando el SDK oficial
@modelcontextprotocol/sdk.Los usuarios solo necesitan configurar
ARK_API_KEYen su propia máquina para invocar la generación de texto a video / imagen a video / referencia multimodal de Seedance 2.0.
Herramientas MCP proporcionadas
Herramienta | Función |
| Devuelve instrucciones de uso completas: flujo estándar, selección de modelo, tabla de parámetros, precauciones. |
| Envía una tarea de generación de video de Seedance 2.0, devuelve |
| Consulta el estado de la tarea con |
Para parámetros detallados, ver Detalles de las herramientas.
Related MCP server: Seedance MCP
Sugerencias de acceso rápido para agentes locales
Si estás utilizando Codex, Claude Desktop, Cursor u otro agente local compatible con MCP, puedes enviarle directamente el enlace a este repositorio y pedirle que lea esta sección.
你是一个本地开发 Agent。请帮我把这个仓库提供的 seedance-2-mcp 接入到当前 MCP 客户端中。
目标:
1. 读取仓库 README,理解这是一个 stdio MCP server,用于调用火山方舟 Seedance 2.0 视频生成 API。
2. 优先使用 npx 方式接入:command = "npx",args = ["-y", "seedance-2-mcp"]。
3. 如果 npm 包暂不可用,或我明确想从源码运行,请 clone 本仓库,执行 npm install && npm run build,并将 MCP command 配为 "node",args 配为 ["<仓库绝对路径>/dist/index.js"]。
4. 只向我索要或确认 ARK_API_KEY,不要把真实 API Key 写进仓库、README、示例文件或 git。
5. 根据我当前使用的客户端自动修改对应 MCP 配置:
- Codex:修改 ~/.codex/config.toml
- Claude Desktop:修改 claude_desktop_config.json
- Cursor 或其他客户端:使用它们支持的 stdio MCP 配置格式
6. 配置完成后,提醒我重启或刷新 MCP 客户端,然后先调用 seedance_usage_guide,再按 create -> wait -> check 的流程生成视频。
7. 如果本机没有 Node.js >= 18 或 npx 不可用,请先指出缺失项,并给出最小安装建议。
重要约束:
- stdout 是 MCP JSON-RPC 通道,不要让 server 在 stdout 打调试日志。
- ARK_API_KEY 只能放在 MCP 客户端 env 配置或本机环境变量里。
- 生成的 video_url 通常会过期,任务成功后应提示我尽快下载。También puedes decirle directamente al agente:
Lee este repositorio y ayúdame a configurar Seedance MCP siguiendo las "Sugerencias de acceso rápido para agentes locales" en el README. Proporcionaré la
ARK_API_KEY.
Instalación
1. A través de npx (Recomendado - no requiere instalación manual)
Úsalo directamente en la configuración del cliente MCP:
npx -y seedance-2-mcpSe descargará (o reutilizará la caché) la última versión en cada inicio.
2. Instalación global
npm install -g seedance-2-mcpDespués, simplemente usa seedance-2-mcp en la configuración del cliente.
3. Ejecución desde el código fuente (desarrolladores)
git clone https://github.com/seedance/seedance-2-mcp.git
cd seedance-2-mcp
npm install
npm run build
node dist/index.jsRequiere Node.js >= 18 (depende de fetch nativo).
Variables de entorno
Variable | Obligatorio | Descripción |
| Sí | API Key de Volcengine ARK. Visita https://console.volcengine.com/ark para obtenerla. |
| No | Por defecto |
Copia .env.example a .env local solo como referencia de desarrollo; la ubicación donde realmente surte efecto es en el campo env de la configuración del cliente MCP, ya que el cliente inicia el MCP a través de un subproceso e inyecta las variables de entorno por sí mismo.
Si no se configura ARK_API_KEY al llamar a la herramienta, las dos herramientas que invocan la API real devolverán un error claro:
Missing ARK_API_KEY environment variable. Please set ARK_API_KEY to your Volcengine ARK API key.
Ejemplos de configuración del cliente
Codex (~/.codex/config.toml)
[mcp_servers.seedance-2-mcp]
command = "npx"
args = ["-y", "seedance-2-mcp"]
env = { "ARK_API_KEY" = "your_key_here" }Claude Desktop (claude_desktop_config.json)
Ruta en macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Ruta en Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"seedance-2-mcp": {
"command": "npx",
"args": ["-y", "seedance-2-mcp"],
"env": {
"ARK_API_KEY": "your_key_here"
}
}
}
}Cursor / Otros clientes MCP
Configuración general para cualquier cliente que soporte stdio MCP:
{
"command": "npx",
"args": ["-y", "seedance-2-mcp"],
"env": { "ARK_API_KEY": "your_key_here" }
}Detalles de las herramientas
seedance_usage_guide
Sin parámetros. Devuelve instrucciones de uso completas en formato Markdown. Se recomienda llamar una vez antes de la primera llamada a seedance_create_task.
seedance_create_task
Envía una tarea de generación de video, devuelve task_id inmediatamente.
Parámetros de entrada:
Campo | Tipo | Por defecto | Descripción |
| string | — (Obligatorio) | Descripción en lenguaje natural. Si hay material de referencia, usa |
| enum |
|
|
| integer |
| Duración del video en segundos. |
| enum |
|
|
| enum |
|
|
| boolean |
| Si se debe generar audio sincronizado (diálogo / efectos de sonido / BGM). |
| boolean |
| Si se debe añadir la marca de agua de la plataforma. Algunas cuentas podrían no poder desactivarla. |
| boolean |
| Si se habilita la mejora de búsqueda web para el prompt; solo disponible para entrada de texto puro, no se puede usar con image/video/audio simultáneamente. |
| boolean |
| Si se devuelve la URL de la imagen del último fotograma, para empalme de segmentos. |
| array | — | Máximo 9 elementos; cada uno |
| array | — | Máximo 3 elementos; cada uno |
| array | — | Máximo 3 elementos; cada uno |
Reglas de validación:
durationdebe ser un entero entre[4, 15].image_urls≤ 9,video_urls≤ 3,audio_urls≤ 3.Se rechazará la combinación de solo texto +
audio_urls(Seedance no lo soporta).Se rechazará
web_search=truejunto con cualquier material de referencia (la mejora de búsqueda web solo soporta texto puro).
Retorno:
{
"task_id": "cgt-2026xxxx-xxxxxx",
"model": "doubao-seedance-2-0-260128",
"duration": 5,
"ratio": "16:9",
"resolution": "720p",
"raw": { /* 火山原始响应 */ }
}seedance_check_task
Entrada { task_id: string }. Estados posibles:
running/queued/pending— Procesando. Se sugiere esperar 30-90 segundos antes de volver a llamar.succeeded— Devuelvevideo_url, sireturn_last_frame=truetambién devuelvelast_frame_url.failed— Devuelvefail_reason(si existe).cancelled/expired— Tarea cancelada o expirada.Otros — Devuelve
statusy el payload original tal cual.
Flujo de llamada típico
client → seedance_usage_guide ← 阅读规则
client → seedance_create_task { prompt, ... } ← 提交任务
↓
task_id: cgt-...
↓
client → seedance_check_task { task_id } ← 30-90s 后轮询
↓
status: running (继续等待)
↓
status: succeeded ← 返回 video_url
↓
立刻下载 video_url(约 24h 内会过期)Las tareas del modelo estándar de 15 segundos suelen tardar entre 2 y 5 minutos en completarse; la versión rápida será más corta.
Notas de seguridad
No escribas
ARK_API_KEYen el repositorio git. Ponla en el campoenvde la configuración del cliente MCP (comoclaude_desktop_config.json,~/.codex/config.toml), o en las variables de entorno del shell.Esta herramienta no imprimirá
ARK_API_KEYen los registros o valores de retorno.Las
video_urlylast_frame_urlgeneradas por Volcengine son URLs temporales con firma, válidas por defecto durante 24 horas según las instrucciones oficiales de Volcengine; descarga los archivos lo antes posible después de que la tarea tenga éxito para evitar que el enlace expire.Las
image_urls/video_urls/audio_urlsque proporciones deben ser direcciones HTTPS (o HTTP) accesibles desde la red pública; las rutas locales, direcciones de intranet o recursos que requieran inicio de sesión no pueden ser recuperados por el servidor de Volcengine.Por favor, cumple con los términos de uso de Volcengine ARK y el modelo Seedance, no generes contenido ilegal, inapropiado para menores o que infrinja derechos de autor.
Desarrollo
npm install
npm run typecheck
npm run dev # 用 tsx 直接跑 src/index.ts
npm run build # 输出到 dist/
npm start # node dist/index.jsPara depurar stdio MCP se recomienda:
npx -y @modelcontextprotocol/inspector npx -y seedance-2-mcpO el código fuente local:
npx -y @modelcontextprotocol/inspector node dist/index.jsEstructura del proyecto
.
├── src/
│ ├── index.ts # stdio MCP 入口(带 shebang)
│ ├── server.ts # 注册 McpServer 和三个 tools
│ ├── seedance.ts # 火山方舟 Seedance 2.0 REST API 客户端
│ ├── schema.ts # zod 输入 schema
│ └── usageGuide.ts # seedance_usage_guide 返回的文本
├── package.json
├── tsconfig.json
├── .env.example
├── .gitignore
├── LICENSE
└── README.mdLicencia
MIT © seedance-2-mcp contributors
Este proyecto no tiene relación oficial con ByteDance, Volcengine o Volcengine ARK. Los nombres "Seedance", "Doubao", "火山方舟", etc., son propiedad de sus respectivos titulares.
Available Tools
3 toolsseedance_check_taskCheck Seedance 2.0 task statusARead-onlyIdempotent
Query the status of a Seedance 2.0 task by task_id. Returns running / succeeded / failed / other. On success returns video_url (and last_frame_url if return_last_frame was true). Generated URLs expire within ~24h - download promptly.
Inputs: task_id (required).
seedance_create_taskCreate Seedance 2.0 video generation taskA
Submit a Seedance 2.0 video generation task to the Volcengine ARK API and return the task_id immediately. Does NOT wait for the video to render - poll seedance_check_task afterwards. Reference media URLs must be publicly reachable.
Inputs: prompt (required), model, duration, ratio, +8 more.
seedance_usage_guideSeedance 2.0 usage guideARead-onlyIdempotent
Returns the canonical usage guide for the Seedance 2.0 MCP: standard create -> wait -> check workflow, model choices, parameter reference, and important caveats. Call this before your first seedance_create_task.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a unique and clear purpose: creating a task, checking its status, and providing usage instructions. There is no overlap in functionality.
All tools share the 'seedance_' prefix and follow a noun-based pattern (check_task, create_task, usage_guide), but 'usage_guide' is not a verb_noun like the others, causing minor inconsistency.
With only 3 tools, the set is tightly scoped to the core workflow of generating and monitoring a video task, plus a guide. This is appropriate for the narrow domain.
The tools cover the essential create-and-check workflow, and the guide complements them. However, missing operations like task cancellation or listing are minor gaps but not critical for the basic use case.
Related MCP Connectors
Generate images and videos with Seedance, Veo, Wan, Grok, GPT-Image and Nano Banana via one MCP.
AI image, video, voice and music generation over MCP, routed to Veo 3.1, Seedance 2.5 and more.
AI video generation MCP server for Kling, MiniMax, Luma & Hunyuan with prompt blueprints.
Build, run, schedule, and publish AI video pipelines to YouTube and TikTok from any MCP client.
Related MCP Servers
- AlicenseCqualityDmaintenanceIntegrates Volcengine's Ark API to provide image and video generation and editing capabilities. It supports both local stdio and remote HTTP transport modes for flexible deployment and use.83MIT
- FlicenseAqualityDmaintenanceEnables video generation using the Seedance 2.0 model through MCP, supporting both OpenAI and Volcengine API formats with tools for creating, monitoring, and downloading videos.6-
- FlicenseAqualityDmaintenanceProvides a audio/video creation toolbox via MCP protocol, enabling natural language-based video editing tasks such as image-to-video, video merging, subtitle extraction, and more.93-
- AlicenseNot gradedqualityCmaintenanceMCP server for generating Seedance 2.5 videos via MuAPI, enabling text-to-video, image-to-video, first/last frame, and omni reference workflows with 720p/480p resolution selection.7MIT