Skip to main content
Glama

seedance-2-mcp

npm version License: MIT

오픈 소스 로컬 실행 MCP (Model Context Protocol) 서버로, Volcengine ARK의 Seedance 2.0 비디오 생성 기능을 3개의 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 상세 설명을 참조하세요.


Related MCP server: Seedance MCP

로컬 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

예

Volcengine ARK 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에 대한 웹 검색 강화 활성화 여부; 순수 텍스트 입력에만 사용 가능, 이미지/비디오/오디오와 동시 사용 불가.

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. 이미지 또는 비디오와 함께 사용 필수.

검증 규칙:

  • 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와 원본 페이로드를 그대로 반환.


일반적인 호출 절차

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 필드나 셸 환경 변수에 보관하세요.

  • 본 도구는 로그나 반환값에 ARK_API_KEY를 출력하지 않습니다.

  • Volcengine에서 생성된 video_url 및 last_frame_url은 서명된 임시 URL이며, 공식 설명에 따라 기본적으로 24시간 동안 유효합니다. 작업 성공 후 즉시 다운로드하여 링크 만료를 방지하세요.

  • 입력하는 image_urls / video_urls / audio_urls는 모두 공용 인터넷에서 접근 가능한 HTTPS(또는 HTTP) 주소여야 합니다. 로컬 경로, 내부망 주소, 로그인이 필요한 리소스는 Volcengine 서버에서 가져올 수 없습니다.

  • Volcengine 및 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

본 프로젝트는 ByteDance, Volcengine, Volcengine ARK와 공식적인 관련이 없습니다. "Seedance", "Doubao", "火山方舟" 등의 명칭은 각 소유자의 저작권입니다.

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
NameRequiredDescriptionDefault
task_idYesSeedance 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
NameRequiredDescriptionDefault
promptYesNatural-language description of the desired video. Reference images / videos / audios with [Image1], [Video1], [Audio1] in 1-based order if you provided any.
modelNoSeedance 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
durationNoVideo length in seconds. Must be an integer in [4, 15].
ratioNoAspect 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
resolutionNoOutput resolution. 720p is recommended; 480p is faster/cheaper.720p
generate_audioNoWhether to generate synchronized audio (dialogue, SFX, music). Set false for silent video.
watermarkNoWhether to add the platform watermark. Some accounts cannot disable this.
web_searchNoEnable prompt enhancement via web search. Text-only input is required when this is true.
return_last_frameNoReturn the last frame as an image URL alongside the video URL. Useful for chaining segments.
image_urlsNoUp 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_urlsNoUp to 3 reference videos. Each item is { url, role? }. role defaults to 'reference_video'.
audio_urlsNoUp 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
NameRequiredDescriptionDefault

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.

  1. 3 tool updatesv0.1.0
    • First observedseedance_check_task
    • First observedseedance_create_task
    • First observedseedance_usage_guide

TDQS

A4.4/5.0

Scored 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

Related MCP Connectors

Related MCP Servers