seedance-2-mcp
seedance-2-mcp
一个开源、本地运行的 MCP (Model Context Protocol) 服务器,把火山方舟 (Volcengine ARK) Seedance 2.0 视频生成能力以三个 stdio 工具的形式暴露给 Codex、Claude Desktop、Cursor 等任意 MCP 客户端。
纯本地 stdio,不需要任何云端部署。
由 Node.js + TypeScript 编写,使用官方
@modelcontextprotocol/sdk。用户在自己机器上配置
ARK_API_KEY即可调用 Seedance 2.0 的 文生视频 / 图生视频 / 多模态参考生成。
提供的 MCP Tools
Tool | 作用 |
| 返回完整的使用说明 — 标准流程、模型选择、参数表、注意事项。 |
| 提交一个 Seedance 2.0 视频生成任务,立即返回 |
| 用 |
详细参数见 Tools 详解。
Related MCP server: Seedance MCP
给本地 Agent 的快速接入提示词
如果你正在使用 Codex、Claude Desktop、Cursor 或其他支持 MCP 的本地 Agent,可以直接把本仓库链接发给它,并让它阅读这一段。
你是一个本地开发 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 通常会过期,任务成功后应提示我尽快下载。你也可以直接对 Agent 说:
阅读这个仓库并按 README 里的“给本地 Agent 的快速接入提示词”帮我配置 Seedance MCP。我会提供
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 Key。前往 https://console.volcengine.com/ark 获取。 |
| 否 | 默认 |
复制 .env.example 到本地 .env 仅作开发参考;真正生效的位置是 MCP 客户端配置里的 env,
因为客户端通过子进程拉起 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" }
}Tools 详解
seedance_usage_guide
无参数。返回 Markdown 格式的完整使用说明。建议在首次调用 seedance_create_task 之前先调用一次。
seedance_create_task
提交一个视频生成任务,立即返回 task_id。
输入参数:
字段 | 类型 | 默认 | 说明 |
| string | —(必填) | 自然语言描述。如有参考素材,在 prompt 中用 |
| enum |
|
|
| integer |
| 视频时长,单位秒。 |
| enum |
|
|
| enum |
|
|
| boolean |
| 是否同时生成同步音频(对白 / 音效 / BGM)。 |
| boolean |
| 是否添加平台水印。部分账号可能无法关闭。 |
| boolean |
| 是否对 prompt 启用联网增强;仅纯文本输入可用,不能与 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 仓库。把它放在 MCP 客户端配置(如claude_desktop_config.json、~/.codex/config.toml)的env字段,或者 shell 环境变量里。本工具不会在日志或返回值里打印
ARK_API_KEY。火山生成的
video_url和last_frame_url是带签名的临时 URL,根据火山官方说明默认 24 小时内有效;任务成功后请尽快下载,避免链接过期。你传入的
image_urls/video_urls/audio_urls都需要 公网可访问 的 HTTPS(或 HTTP)地址;本地路径、内网地址、需要登录的资源无法被火山服务器拉取。请遵守火山方舟与 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
本项目与字节跳动、火山引擎、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