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_KEY en 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

Para parámetros detallados, ver Detalles de las herramientas.

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-mcp

Se descargará (o reutilizará la caché) la última versión en cada inicio.

2. Instalación global

npm install -g seedance-2-mcp

Despué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.js

Requiere Node.js >= 18 (depende de fetch nativo).

Variables de entorno

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:

Reglas de validación:

• duration debe 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=true junto 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 — Devuelve video_url, si return_last_frame=true también devuelve last_frame_url.

• failed — Devuelve fail_reason (si existe).

• cancelled / expired — Tarea cancelada o expirada.

• Otros — Devuelve status y 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_KEY en el repositorio git. Ponla en el campo env de la configuración del cliente MCP (como claude_desktop_config.json, ~/.codex/config.toml), o en las variables de entorno del shell.

• Esta herramienta no imprimirá ARK_API_KEY en los registros o valores de retorno.

• Las video_url y last_frame_url generadas 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_urls que 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.js

Para depurar stdio MCP se recomienda:

npx -y @modelcontextprotocol/inspector npx -y seedance-2-mcp

O el código fuente local:

npx -y @modelcontextprotocol/inspector node dist/index.js

Estructura 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.md

Licencia

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.