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_usage_guide	返回完整的使用说明 — 标准流程、模型选择、参数表、注意事项。
seedance_create_task	提交一个 Seedance 2.0 视频生成任务，立即返回 task_id，不阻塞。
seedance_check_task	用 task_id 查询任务状态，成功后返回 video_url 和可选末帧图片。

详细参数见 Tools 详解。

---

给本地 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）。

---

环境变量

变量	必填	说明
ARK_API_KEY	是	火山方舟 API Key。前往 https://console.volcengine.com/ark 获取。
ARK_BASE_URL	否	默认 https://ark.cn-beijing.volces.com/api/v3。海外/代理可覆盖。

复制 .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。

输入参数：

字段	类型	默认	说明
prompt	string	—（必填）	自然语言描述。如有参考素材，在 prompt 中用 [Image1] / [Video1] / [Audio1] 引用。
model	enum	doubao-seedance-2-0-260128	doubao-seedance-2-0-260128（标准版，最高质量）/ doubao-seedance-2-0-fast-260128（快速版）。
duration	integer	5	视频时长，单位秒。[4, 15]。
ratio	enum	16:9	21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive。
resolution	enum	720p	480p 或 720p。
generate_audio	boolean	true	是否同时生成同步音频（对白 / 音效 / BGM）。
watermark	boolean	true	是否添加平台水印。部分账号可能无法关闭。
web_search	boolean	false	是否对 prompt 启用联网增强；仅纯文本输入可用，不能与 image/video/audio 同时使用。
return_last_frame	boolean	false	是否返回末帧图片 URL，用于多段拼接。
image_urls	array	—	最多 9 项；每项 { url, role? }，role ∈ reference_image / first_frame / last_frame，默认 reference_image。
video_urls	array	—	最多 3 项；每项 { url, role? }，role ∈ reference_video。
audio_urls	array	—	最多 3 项；每项 { url, role? }，role ∈ reference_audio。必须配合 image 或 video。

校验规则：

• 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"、"火山方舟" 等名称版权归各自持有人所有。