火山方舟 Seedream / Seedance MCP 服务

一个基于火山方舟（Ark）API 的 MCP 服务，提供：

• Seedream 图片生成/编辑
• Seedance 视频生成（异步任务）
• 本地 stdio 与远程 http 两种接入模式

功能概览

能力	状态	说明
图片生成/编辑	可用	基于 POST /api/v3/images/generations
视频生成	可用	基于 POST /api/v3/contents/generations/tasks + 查询任务
本地接入	可用	StdioServerTransport
远程接入	可用	StreamableHTTPServerTransport

快速开始

环境要求

• Node.js 18+
• pnpm

安装依赖

pnpm install

构建

pnpm build

环境变量

变量名	必填	默认值	说明
ARK_API_KEY	是	-	火山方舟 API Key
MCP_TRANSPORT	否	stdio	传输模式：stdio 或 http
MCP_HTTP_HOST	否	0.0.0.0	http 模式监听地址
MCP_HTTP_PORT	否	3000	http 模式监听端口
MCP_HTTP_PATH	否	/mcp	http 模式 MCP 路径

可在项目根目录创建 .env：

ARK_API_KEY=your_ark_api_key
MCP_TRANSPORT=stdio

启动方式

1. 本地模式（默认，stdio）

pnpm build
node build/index.js

2. 远程模式（http）

PowerShell 示例：

$env:ARK_API_KEY="your_ark_api_key"
$env:MCP_TRANSPORT="http"
$env:MCP_HTTP_HOST="0.0.0.0"
$env:MCP_HTTP_PORT="3000"
$env:MCP_HTTP_PATH="/mcp"
node build/index.js

服务启动后地址示例：

http://127.0.0.1:3000/mcp

MCP 客户端接入

本地命令方式（stdio）

{
  "mcpServers": {
    "jimenggen": {
      "command": "node",
      "args": [
        "/path/to/jimenggen-mcp/build/index.js"
      ],
      "env": {
        "ARK_API_KEY": "your_ark_api_key",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

远程地址方式（http）

不同客户端配置字段可能不同，核心是把 MCP 服务地址指向：

http://your-host:3000/mcp

工具列表

可用工具

工具名	用途
text-to-image	文生图
image-to-image	图生图
generate-image	通用图片生成/编辑（支持 URL 与上传文件）
generate-img-seedream4	直接调用 Seedream API 生成图片
generate-video	视频生成（异步任务，内置轮询）

停用工具

• generate-digital-human
• action-imitation
• image-dressing

模型清单

Seedream（图片）

• doubao-seedream-5-0-lite-260128（默认）
• doubao-seedream-5-0-260128
• doubao-seedream-4-5-251128
• doubao-seedream-4-0-250828

Seedance（视频）

• doubao-seedance-1-5-pro-251215（默认）
• doubao-seedance-1-0-pro-250528
• doubao-seedance-1-0-pro-fast-251015
• doubao-seedance-1-0-lite-t2v-250428
• doubao-seedance-1-0-lite-i2v-250428

视频生成（generate-video）

generate-video 使用异步任务流程：

1. 创建任务：POST /contents/generations/tasks
2. 查询任务：GET /contents/generations/tasks/{id}
3. 成功后读取：content.video_url

任务状态：

• queued
• running
• succeeded
• failed
• expired

主要参数：

参数	类型	说明
prompt	string	必填，视频提示词
model	string	可选，默认 doubao-seedance-1-5-pro-251215
duration	5/10	可选，默认 5 秒
ratio	enum	可选：adaptive、16:9、4:3、1:1、3:4、9:16、21:9
imageUrl	string	可选，首帧图 URL（图生视频）
generate_audio	boolean	可选，默认 true
watermark	boolean	可选，默认 false
callback_url	string	可选，任务状态回调地址
poll_interval_ms	number	可选，默认 10000
max_poll_attempts	number	可选，默认 60

兼容参数映射：

• frames=121 映射为 duration=5
• frames=241 映射为 duration=10
• aspect_ratio 在值合法时映射到 ratio

说明：根据官方文档，Seedance 2.0 当前仅支持控制台体验，暂不支持 API 调用。

常见问题

1. 报错：未设置 ARK_API_KEY

请确认环境变量已设置，并且启动进程能读取该变量。

2. http 模式返回 404

请检查客户端访问路径是否与 MCP_HTTP_PATH 一致，默认是 /mcp。

3. 视频任务超时

可适当调大 max_poll_attempts，或增大 poll_interval_ms 后重试。

参考文档

• 视频生成教程：https://www.volcengine.com/docs/82379/1366799?lang=zh
• 视频 API 参考：https://www.volcengine.com/docs/82379/1520758?lang=zh
• 快速入门（API Key）：https://www.volcengine.com/docs/82379/1399008?lang=zh
• Seedream 教程：https://www.volcengine.com/docs/82379/1824121?lang=zh
• 模型列表：https://www.volcengine.com/docs/82379/1330310