seedance-2-mcp

An open-source, locally-run MCP (Model Context Protocol) server that exposes the Volcengine ARK Seedance 2.0 video generation capabilities as three stdio tools to any MCP client, such as Codex, Claude Desktop, or Cursor.

• Pure local stdio, no cloud deployment required.

• Built with Node.js + TypeScript, using the official @modelcontextprotocol/sdk.

• Users can configure ARK_API_KEY on their own machines to invoke Seedance 2.0's text-to-video / image-to-video / multimodal reference generation.

Provided MCP Tools

See Detailed Tools for parameter details.

Related MCP server: Seedance MCP

Quick Access Prompt for Local Agents

If you are using Codex, Claude Desktop, Cursor, or other local agents that support MCP, you can send this repository link directly to it and ask it to read this section.

你是一个本地开发 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 通常会过期，任务成功后应提示我尽快下载。

You can also say to the Agent directly:

Read this repository and help me configure Seedance MCP according to the "Quick Access Prompt for Local Agents" in the README. I will provide the ARK_API_KEY.

Installation

1. Via npx (Recommended - No manual installation required)

Use directly in the MCP client configuration:

npx -y seedance-2-mcp

It will download (or reuse cache) the latest version every time it starts.

2. Global Installation

npm install -g seedance-2-mcp

After that, use seedance-2-mcp in your client configuration.

3. Run from Source (Developers)

git clone https://github.com/seedance/seedance-2-mcp.git
cd seedance-2-mcp
npm install
npm run build
node dist/index.js

Requires Node.js >= 18 (depends on native fetch).

Environment Variables

Copy .env.example to a local .env for development reference only; the actual effective location is the env field in the MCP client configuration, because the client launches the MCP via a child process and injects environment variables itself.

If ARK_API_KEY is not set when a tool is called, the two tools that call the actual API will return a clear error:

Missing ARK_API_KEY environment variable. Please set ARK_API_KEY to your Volcengine ARK API key.

Client Configuration Examples

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 path: ~/Library/Application Support/Claude/claude_desktop_config.json Windows path: %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 / Other MCP Clients

General configuration for any client supporting stdio MCP:

{
  "command": "npx",
  "args": ["-y", "seedance-2-mcp"],
  "env": { "ARK_API_KEY": "your_key_here" }
}

Detailed Tools

seedance_usage_guide

No parameters. Returns complete usage instructions in Markdown format. It is recommended to call this once before the first call to seedance_create_task.

seedance_create_task

Submits a video generation task, returns task_id immediately.

Input parameters:

Validation rules:

• duration must be an integer between [4, 15].

• image_urls ≤ 9, video_urls ≤ 3, audio_urls ≤ 3.

• Pure text + audio_urls will be rejected (Seedance does not support this).

• web_search=true appearing with any reference material will be rejected (web enhancement only supports pure text).

Returns:

{
  "task_id": "cgt-2026xxxx-xxxxxx",
  "model": "doubao-seedance-2-0-260128",
  "duration": 5,
  "ratio": "16:9",
  "resolution": "720p",
  "raw": { /* 火山原始响应 */ }
}

seedance_check_task

Input { task_id: string }. Possible statuses:

• running / queued / pending — Still processing. Suggest waiting 30-90 seconds before calling again.

• succeeded — Returns video_url, and last_frame_url if return_last_frame=true.

• failed — Returns fail_reason (if any).

• cancelled / expired — Task cancelled or expired.

• Others — Returns status and original payload as is.

Typical Workflow

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-second standard model tasks usually take 2-5 minutes to complete; the fast version will be shorter.

Security Notes

• Do not commit ARK_API_KEY to git repositories. Put it in the env field of your MCP client configuration (e.g., claude_desktop_config.json, ~/.codex/config.toml), or in shell environment variables.

• This tool will not print ARK_API_KEY in logs or return values.

• The video_url and last_frame_url generated by Volcengine are signed temporary URLs, which are valid for 24 hours by default according to official Volcengine documentation; please download them as soon as possible after the task succeeds to avoid link expiration.

• The image_urls / video_urls / audio_urls you provide must be HTTPS (or HTTP) addresses accessible from the public internet; local paths, intranet addresses, or resources requiring login cannot be fetched by Volcengine servers.

• Please comply with the terms of service for Volcengine ARK and Seedance models, and do not generate illegal, inappropriate for minors, or infringing content.

Development

npm install
npm run typecheck
npm run dev          # 用 tsx 直接跑 src/index.ts
npm run build        # 输出到 dist/
npm start            # node dist/index.js

For debugging stdio MCP, it is recommended to use:

npx -y @modelcontextprotocol/inspector npx -y seedance-2-mcp

Or local source code:

npx -y @modelcontextprotocol/inspector node dist/index.js

Project Structure

.
├── 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

License

MIT © seedance-2-mcp contributors

This project has no official affiliation with ByteDance, Volcengine, or Volcengine ARK. "Seedance", "Doubao", "Volcengine ARK", and other names are the property of their respective owners.