seedance-2-mcp
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
Инструмент | Назначение |
| Возвращает полное руководство по использованию — стандартный процесс, выбор модели, таблица параметров, примечания. |
| Отправляет задачу на генерацию видео Seedance 2.0, немедленно возвращает |
| Использует |
Подробные параметры см. в разделе Подробности об инструментах.
Related MCP server: Seedance 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).
Переменные окружения
Переменная | Обязательно | Описание |
| Да | API-ключ Volcengine ARK. Получите на https://console.volcengine.com/ark. |
| Нет | По умолчанию |
Скопируйте .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.
Входные параметры:
Поле | Тип | По умолчанию | Описание |
| string | — (обязательно) | Описание на естественном языке. При наличии референсных материалов используйте |
| enum |
|
|
| integer |
| Длительность видео в секундах. |
| enum |
|
|
| enum |
|
|
| boolean |
| Генерировать ли синхронный звук (диалоги / звуковые эффекты / фоновая музыка). |
| boolean |
| Добавлять ли водяной знак платформы. Некоторые аккаунты могут не иметь возможности отключения. |
| boolean |
| Включить ли расширение промпта через поиск в сети; доступно только для чистого текста, нельзя использовать вместе с image/video/audio. |
| boolean |
| Возвращать ли URL изображения последнего кадра для склейки сегментов. |
| array | — | Максимум 9 элементов; каждый |
| array | — | Максимум 3 элемента; каждый |
| array | — | Максимум 3 элемента; каждый |
Правила проверки:
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", "火山方舟" и другие принадлежат их соответствующим владельцам.
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