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 비디오 생성 작업 제출, .
`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`	예	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 서버에서 가져올 수 없습니다.

개발

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

seedance-2-mcp

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`

일반적인 호출 절차

보안 주의사항

개발

프로젝트 구조

라이선스

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API

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

일반적인 호출 절차

보안 주의사항

개발

프로젝트 구조

라이선스

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API

1. `npx`를 통한 실행 (권장 - 수동 설치 불필요)

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

Claude Desktop (`claude_desktop_config.json`)

`seedance_usage_guide`

`seedance_create_task`

`seedance_check_task`