seedance-2-mcp

Сервер MCP (Model Context Protocol) с открытым исходным кодом, работающий локально, который предоставляет возможности генерации видео Seedance 2.0 от Volcengine ARK в виде трех инструментов stdio для любых MCP-клиентов, таких как Codex, Claude Desktop, Cursor и других.

• Полностью локальный stdio, не требует развертывания в облаке.

• Написан на Node.js + TypeScript с использованием официального SDK @modelcontextprotocol/sdk.

• Пользователи могут настроить ARK_API_KEY на своей машине для вызова функций текст-в-видео / изображение-в-видео / мультимодальная генерация по референсам Seedance 2.0.

Предоставляемые инструменты MCP

Подробные параметры см. в разделе Подробности об инструментах.

Быстрые подсказки для локальных агентов

Если вы используете Codex, Claude Desktop, Cursor или другой локальный агент с поддержкой MCP, вы можете отправить ему ссылку на этот репозиторий и попросить прочитать этот раздел.

你是一个本地开发 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 通常会过期，任务成功后应提示我尽快下载。

Вы также можете напрямую сказать агенту:

Прочитай этот репозиторий и помоги мне настроить Seedance MCP в соответствии с разделом «Быстрые подсказки для локальных агентов» в README. Я предоставлю ARK_API_KEY.

Установка

1. Через npx (рекомендуется — ручная установка не требуется)

Используйте напрямую в конфигурации MCP-клиента:

npx -y seedance-2-mcp

При каждом запуске будет скачиваться (или использоваться из кэша) последняя версия.

2. Глобальная установка

npm install -g seedance-2-mcp

После этого используйте seedance-2-mcp в конфигурации клиента.

3. Запуск из исходного кода (для разработчиков)

git clone https://github.com/seedance/seedance-2-mcp.git
cd seedance-2-mcp
npm install
npm run build
node dist/index.js

Требуется Node.js >= 18 (зависит от нативного fetch).

Переменные окружения

Скопируйте .env.example в локальный .env только для целей разработки; реальное место применения — поле env в конфигурации MCP-клиента, так как клиент запускает MCP через дочерний процесс и сам внедряет переменные окружения.

Если ARK_API_KEY не задан при вызове инструмента, два инструмента, вызывающие реальный API, вернут четкую ошибку:

Missing ARK_API_KEY environment variable. Please set ARK_API_KEY to your Volcengine ARK API key.

Примеры конфигурации клиента

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)

Путь для macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Путь для 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 / Другие MCP-клиенты

Общая конфигурация для любого клиента с поддержкой stdio MCP:

{
  "command": "npx",
  "args": ["-y", "seedance-2-mcp"],
  "env": { "ARK_API_KEY": "your_key_here" }
}

Подробности об инструментах

seedance_usage_guide

Без параметров. Возвращает полное руководство по использованию в формате Markdown. Рекомендуется вызвать один раз перед первым вызовом seedance_create_task.

seedance_create_task

Отправляет задачу на генерацию видео, немедленно возвращает task_id.

Входные параметры:

Правила проверки:

• duration должно быть целым числом в диапазоне [4, 15].

• image_urls ≤ 9, video_urls ≤ 3, audio_urls ≤ 3.

• Комбинация только чистого текста + audio_urls будет отклонена (Seedance не поддерживает).

• web_search=true вместе с любыми референсными материалами будет отклонено (поиск в сети поддерживает только чистый текст).

Возвращает:

{
  "task_id": "cgt-2026xxxx-xxxxxx",
  "model": "doubao-seedance-2-0-260128",
  "duration": 5,
  "ratio": "16:9",
  "resolution": "720p",
  "raw": { /* 火山原始响应 */ }
}

seedance_check_task

Входные данные { task_id: string }. Возможные статусы:

• running / queued / pending — в процессе обработки. Рекомендуется подождать 30-90 секунд перед повторным вызовом.

• succeeded — возвращает video_url, если return_last_frame=true, также возвращает last_frame_url.

• failed — возвращает fail_reason (если есть).

• cancelled / expired — задача отменена или истекла.

• Другое — возвращает status и исходный payload без изменений.

Типичный процесс вызова

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 内会过期）

Стандартная задача на 15 секунд обычно занимает 2-5 минут; быстрая версия выполняется быстрее.

Примечания по безопасности

• Не записывайте ARK_API_KEY в git-репозиторий. Поместите его в поле env конфигурации MCP-клиента (например, claude_desktop_config.json, ~/.codex/config.toml) или в переменные окружения оболочки.

• Этот инструмент не выводит ARK_API_KEY в логи или возвращаемые значения.

• video_url и last_frame_url, сгенерированные Volcengine, являются временными URL с подписью, которые, согласно официальной документации, действительны в течение 24 часов; скачивайте их сразу после завершения задачи, чтобы избежать истечения срока действия ссылок.

• Передаваемые вами image_urls / video_urls / audio_urls должны быть доступны из публичной сети по HTTPS (или HTTP); локальные пути, адреса внутренней сети или ресурсы, требующие авторизации, не могут быть получены серверами Volcengine.

• Пожалуйста, соблюдайте условия использования Volcengine ARK и модели Seedance, не генерируйте незаконный, неприемлемый для несовершеннолетних или нарушающий авторские права контент.

Разработка

npm install
npm run typecheck
npm run dev          # 用 tsx 直接跑 src/index.ts
npm run build        # 输出到 dist/
npm start            # node dist/index.js

Для отладки stdio MCP рекомендуется:

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

Или локальные исходники:

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

Структура проекта

.
├── 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

Лицензия

MIT © seedance-2-mcp contributors

Данный проект не имеет официальной связи с ByteDance, Volcengine или Volcengine ARK. Названия "Seedance", "Doubao", "火山方舟" и другие принадлежат их соответствующим владельцам.