seedance-2-mcp
seedance-2-mcp
오픈 소스 로컬 실행 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 2.0 비디오 생성 작업 제출, 즉시 |
|
|
상세 매개변수는 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.jsNode.js >= 18 필요 (네이티브 fetch 의존).
환경 변수
변수 | 필수 | 설명 |
| 예 | Volcengine ARK API Key. https://console.volcengine.com/ark 에서 획득. |
| 아니오 | 기본값 |
.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를 반환합니다.
입력 매개변수:
필드 | 타입 | 기본값 | 설명 |
| string | — (필수) | 자연어 설명. 참조 자료가 있는 경우 prompt 내에서 |
| enum |
|
|
| integer |
| 비디오 길이(초). |
| enum |
|
|
| enum |
|
|
| boolean |
| 동기화된 오디오(대사 / 효과음 / BGM) 생성 여부. |
| boolean |
| 플랫폼 워터마크 추가 여부. 일부 계정은 비활성화가 불가능할 수 있음. |
| boolean |
| prompt에 대한 웹 검색 강화 활성화 여부; 순수 텍스트 입력에만 사용 가능, 이미지/비디오/오디오와 동시 사용 불가. |
| boolean |
| 다중 세그먼트 연결을 위해 마지막 프레임 이미지 URL 반환 여부. |
| array | — | 최대 9개; 각 항목 |
| array | — | 최대 3개; 각 항목 |
| array | — | 최대 3개; 각 항목 |
검증 규칙:
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.jsstdio 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", "火山方舟" 등의 명칭은 각 소유자의 저작권입니다.
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Servers
- AlicenseCqualityDmaintenanceIntegrates 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.8613MIT
- FlicenseAqualityCmaintenanceEnables 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.6
- FlicenseNot gradedqualityDmaintenanceProvides 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.3
- AlicenseAqualityCmaintenanceMCP 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.31MIT
Related MCP Connectors
MCP server for ByteDance Seedance AI video generation
MCP server for Google Veo AI video generation
MCP server for Kling AI video generation
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/leonaiuv/seedance-2-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server