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

协议

本项目与字节跳动、火山引擎、Volcengine ARK 均无官方关联。 "Seedance"、"Doubao"、"火山方舟" 等名称版权归各自持有人所有。

MCP Servers

seedance-2-mcp

提供的 MCP Tools

给本地 Agent 的快速接入提示词

安装

1. 通过 `npx`（推荐 - 无需手动安装）

2. 全局安装

3. 从源码运行（开发者）

环境变量

客户端配置示例

Codex（`~/.codex/config.toml`）

Claude Desktop（`claude_desktop_config.json`）

Cursor / 其他 MCP 客户端

Tools 详解

`seedance_usage_guide`

`seedance_create_task`

`seedance_check_task`

典型调用流程

安全说明

开发

项目结构

协议

安装包（如果需要）

Cursor 配置 (mcp.json)

seedance-2-mcp

提供的 MCP Tools

给本地 Agent 的快速接入提示词

安装

1. 通过 npx（推荐 - 无需手动安装）

2. 全局安装

3. 从源码运行（开发者）

环境变量

客户端配置示例

Codex（~/.codex/config.toml）

Claude Desktop（claude_desktop_config.json）

Cursor / 其他 MCP 客户端

Tools 详解

seedance_usage_guide

seedance_create_task

seedance_check_task

典型调用流程

安全说明

开发

项目结构

协议

安装包 （如果需要）

Cursor 配置 (mcp.json)

1. 通过 `npx`（推荐 - 无需手动安装）

Codex（`~/.codex/config.toml`）

Claude Desktop（`claude_desktop_config.json`）

`seedance_usage_guide`

`seedance_create_task`

`seedance_check_task`

安装包（如果需要）