How do I use seedance-2-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@seedance-2-mcp create a 10-second video of a futuristic city at night" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

de en es ja ko ru zh

seedance-2-mcp

by leonaiuv

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

seedance-2-mcp

npm version License: MIT

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

Tool	Purpose
`seedance_usage_guide`	Returns complete usage instructions — standard workflow, model selection, parameter table, and notes.
`seedance_create_task`	Submits a Seedance 2.0 video generation task, returns `task_id` immediately, non-blocking.
`seedance_check_task`	Queries task status using `task_id`, returns `video_url` and optional last frame image upon success.

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

Variable	Required	Description
`ARK_API_KEY`	Yes	Volcengine ARK API Key. Visit https://console.volcengine.com/ark to obtain.
`ARK_BASE_URL`	No	Defaults to `https://ark.cn-beijing.volces.com/api/v3`. Can be overridden for overseas/proxy usage.

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:

Field	Type	Default	Description
`prompt`	string	— (Required)	Natural language description. If there are reference materials, use `[Image1]` / `[Video1]` / `[Audio1]` in the prompt to reference them.
`model`	enum	`doubao-seedance-2-0-260128`	`doubao-seedance-2-0-260128` (Standard, highest quality) / `doubao-seedance-2-0-fast-260128` (Fast version).
`duration`	integer	`5`	Video duration in seconds. `[4, 15]`.
`ratio`	enum	`16:9`	`21:9` / `16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `adaptive`.
`resolution`	enum	`720p`	`480p` or `720p`.
`generate_audio`	boolean	`true`	Whether to generate synchronized audio (dialogue / sound effects / BGM) simultaneously.
`watermark`	boolean	`true`	Whether to add a platform watermark. Some accounts may not be able to disable this.
`web_search`	boolean	`false`	Whether to enable web search enhancement for the prompt; only available for pure text input, cannot be used with image/video/audio simultaneously.
`return_last_frame`	boolean	`false`	Whether to return the last frame image URL, used for multi-segment stitching.
`image_urls`	array	—	Up to 9 items; each item `{ url, role? }`, `role` ∈ `reference_image` / `first_frame` / `last_frame`, defaults to `reference_image`.
`video_urls`	array	—	Up to 3 items; each item `{ url, role? }`, `role` ∈ `reference_video`.
`audio_urls`	array	—	Up to 3 items; each item `{ url, role? }`, `role` ∈ `reference_audio`. Must be used with image or video.

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.

Available Tools

3 tools

seedance_check_taskCheck Seedance 2.0 task statusA

Read-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.

ParametersJSON Schema

Name	Required	Description	Default
`task_id`	Yes	Seedance task id returned by seedance_create_task (e.g. cgt-...).

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate readOnly and idempotent. Description adds URL expiration (~24h) and return format, which isn't in annotations. No contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with purpose, no redundant or extraneous content. Efficient and clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Describes statuses and URL expiry without output schema. Adequate for a status check tool; could mention error handling but not required.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 100% coverage with description for task_id. Description adds context that it's the ID from seedance_create_task, improving usability.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it queries status of a Seedance 2.0 task by task_id, lists possible statuses and success returns. Distinguishes from sibling tools (create and guide).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies usage after task creation but does not explicitly state when to use vs alternatives or mention polling patterns. No when-not or alternatives provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`prompt`	Yes	Natural-language description of the desired video. Reference images / videos / audios with [Image1], [Video1], [Audio1] in 1-based order if you provided any.
`model`	No	Seedance 2.0 model id. doubao-seedance-2-0-260128 is the standard, highest-quality model. doubao-seedance-2-0-fast-260128 trades quality for latency.	doubao-seedance-2-0-260128
`duration`	No	Video length in seconds. Must be an integer in [4, 15].
`ratio`	No	Aspect ratio. Use 9:16 for vertical short-video, 16:9 for landscape. 'adaptive' lets the model pick the best fit when reference media is provided.	16:9
`resolution`	No	Output resolution. 720p is recommended; 480p is faster/cheaper.	720p
`generate_audio`	No	Whether to generate synchronized audio (dialogue, SFX, music). Set false for silent video.
`watermark`	No	Whether to add the platform watermark. Some accounts cannot disable this.
`web_search`	No	Enable prompt enhancement via web search. Text-only input is required when this is true.
`return_last_frame`	No	Return the last frame as an image URL alongside the video URL. Useful for chaining segments.
`image_urls`	No	Up to 9 reference images. Each item is { url, role? }. role defaults to 'reference_image'. Use 'first_frame' (and optionally 'last_frame') for image-to-video animation.
`video_urls`	No	Up to 3 reference videos. Each item is { url, role? }. role defaults to 'reference_video'.
`audio_urls`	No	Up to 3 reference audios. Each item is { url, role? }. role defaults to 'reference_audio'. Audio MUST be paired with at least one image or video reference.

TDQS

A4.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate readOnlyHint=false, and the description confirms a mutation (creates a task). It adds context beyond annotations: the async nature ('Does NOT wait for the video to render') and the requirement for public URLs. However, it does not mention rate limits, error handling, or response structure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences containing no fluff: first states core function, second explains async behavior with action, third adds constraint. Front-loaded with the most important information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 12 parameters and no output schema, the description covers the essential workflow and a key constraint (public URLs). It lacks details on error cases or the exact format of the returned task_id, but the async instruction is clear. Overall adequate but could be slightly more detailed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds value beyond schema by emphasizing the async behavior and public URL requirement, which are not evident from individual parameter descriptions. It also clarifies the workflow (submit then poll).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Submit' and the resource 'Seedance 2.0 video generation task'. It specifies that it returns a task_id immediately and does not wait for rendering, distinguishing it from sibling tools like seedance_check_task that are used for polling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly instructs to poll seedance_check_task afterwards and notes that reference media URLs must be publicly reachable. It provides clear guidance on when to use this tool (to initiate a task) and what to do next (poll for results).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

seedance_usage_guideSeedance 2.0 usage guideA

Read-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.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations (readOnlyHint, idempotentHint) already declare safe, idempotent behavior. The description adds that it returns a guide, but no additional behavioral traits beyond what annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no wasted words. Front-loaded with key purpose and usage instruction. Highly concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, no-output-schema guide tool, the description fully explains its purpose, content, and when to use it. No gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, so baseline is 4. The description adds meaning by explaining the tool's purpose and content, compensating for lack of parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it returns the canonical usage guide for Seedance 2.0 MCP, detailing workflow, model choices, parameters, and caveats. It distinguishes itself from sibling tools (check, create) by being the preliminary guide.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit advice to call before first seedance_create_task provides clear context for use. No exclusions or alternatives are needed given its unique role as a guide.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

3 tool updatesv0.1.0May 2, 2026
- First observedseedance_check_task
- First observedseedance_create_task
- First observedseedance_usage_guide

Deploy Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.4/5.0

Scored 2026-05-02 19:30 across 3 tools

Disambiguation5/5

Each tool has a unique and clear purpose: creating a task, checking its status, and providing usage instructions. There is no overlap in functionality.

Naming Consistency4/5

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.

Tool Count5/5

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.

Completeness4/5

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.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

mcp-seedanceOAuth
io.github.AceDataCloud
MCP server for ByteDance Seedance AI video generation
Image & Video Processing Multimedia Processing Entertainment & Media
218
StoryStudioOAuth
io.github.HelloElo-Fr
AI image, video, voice and music generation over MCP, routed to Veo 3.1, Seedance 2.0 and more.
AI & Machine Learning Image & Video Processing Audio Processing
1
TrezaOAuth
io.github.treza-labs
Build, run, schedule, and publish AI video pipelines to YouTube and TikTok from any MCP client.
AI & Machine Learning Image & Video Processing Payments & Billing
1
mcp-veoOAuth
io.github.AceDataCloud
MCP server for Google Veo AI video generation
Multimedia Processing Image & Video Processing Entertainment & Media
23

Related MCP Servers

Seedream/Seedance MCP Server
nsmao-com
A
license
C
quality
D
maintenance
Integrates 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.
Updated 6 months ago (2026-03-05 14:24 UTC)
8
57
3
MIT
Seedance MCP
AI & Machine Learning Multimedia Processing Image & Video Processing
dpspace2050
F
license
A
quality
D
maintenance
Enables 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.
Updated 3 months ago (2026-06-12 11:12 UTC)
6
-
MathMind MCP Server
Multimedia Processing Image & Video Processing Audio Processing
Runninghcm
F
license
A
quality
D
maintenance
Provides 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.
Updated a year ago (2025-08-09 17:53 UTC)
9
3
-
jimeng_visual_generation
Image & Video Processing AI & Machine Learning
justForever17
A
license
A
quality
C
maintenance
MCP server for generating images and videos using Volcengine's Jimeng APIs, supporting text-to-image, image-to-image, multi-image fusion, text-to-video, and image-to-video.
Updated 12 days ago (2026-09-01 07:21 UTC)
3
1
MIT

seedance-2-mcp

Provided MCP Tools

Quick Access Prompt for Local Agents

Installation

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

2. Global Installation

3. Run from Source (Developers)

Environment Variables

Client Configuration Examples

Codex (~/.codex/config.toml)

Claude Desktop (claude_desktop_config.json)

Cursor / Other MCP Clients

Detailed Tools

seedance_usage_guide

seedance_create_task

seedance_check_task

Typical Workflow

Security Notes

Development

Project Structure

License

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

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

Codex (`~/.codex/config.toml`)

Claude Desktop (`claude_desktop_config.json`)

`seedance_usage_guide`

`seedance_create_task`

`seedance_check_task`