Skip to main content
Glama

seedance-2-mcp

npm version License: MIT

Ein Open-Source, lokal ausgeführter MCP (Model Context Protocol) Server, der die Videogenerierungsfunktionen von Volcengine ARK Seedance 2.0 über drei stdio-Tools für MCP-Clients wie Codex, Claude Desktop, Cursor usw. verfügbar macht.

  • Rein lokales stdio, keine Cloud-Bereitstellung erforderlich.

  • Geschrieben in Node.js + TypeScript, unter Verwendung des offiziellen @modelcontextprotocol/sdk.

  • Benutzer können Seedance 2.0 Text-zu-Video / Bild-zu-Video / multimodale Referenzgenerierung nutzen, indem sie einfach ihren ARK_API_KEY auf ihrem eigenen Rechner konfigurieren.


Verfügbare MCP Tools

Tool

Funktion

seedance_usage_guide

Gibt eine vollständige Anleitung zurück — Standardprozess, Modellauswahl, Parametertabelle, Hinweise.

seedance_create_task

Reicht einen Seedance 2.0 Videogenerierungsauftrag ein, gibt sofort task_id zurück, blockiert nicht.

seedance_check_task

Fragt den Status eines Auftrags mit task_id ab; bei Erfolg werden video_url und optional das letzte Frame-Bild zurückgegeben.

Details zu den Parametern finden Sie unter Tools im Detail.


Related MCP server: Seedance MCP

Schnelleinstieg für lokale Agents

Wenn Sie Codex, Claude Desktop, Cursor oder einen anderen MCP-fähigen lokalen Agenten verwenden, können Sie ihm den Link zu diesem Repository senden und ihn bitten, diesen Abschnitt zu lesen.

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

Sie können dem Agenten auch direkt sagen:

Lies dieses Repository und konfiguriere Seedance MCP für mich gemäß den „Schnelleinstieg für lokale Agents“ in der README. Ich werde den ARK_API_KEY bereitstellen.


Installation

1. Über npx (Empfohlen - keine manuelle Installation erforderlich)

Verwenden Sie dies direkt in der Konfiguration des MCP-Clients:

npx -y seedance-2-mcp

Bei jedem Start wird die neueste Version heruntergeladen (oder aus dem Cache verwendet).

2. Globale Installation

npm install -g seedance-2-mcp

Danach können Sie seedance-2-mcp in der Client-Konfiguration verwenden.

3. Aus dem Quellcode ausführen (für Entwickler)

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

Erfordert Node.js >= 18 (abhängig von nativem fetch).


Umgebungsvariablen

Variable

Erforderlich

Beschreibung

ARK_API_KEY

Ja

Volcengine ARK API Key. Besuchen Sie https://console.volcengine.com/ark zum Abrufen.

ARK_BASE_URL

Nein

Standard https://ark.cn-beijing.volces.com/api/v3. Kann für Übersee/Proxy überschrieben werden.

Kopieren Sie .env.example nach .env nur als Referenz für die Entwicklung; der tatsächlich wirksame Ort ist das env-Feld in der MCP-Client-Konfiguration, da der Client den MCP-Prozess als Kindprozess startet und die Umgebungsvariablen selbst injiziert.

Wenn ARK_API_KEY beim Aufruf eines Tools nicht gesetzt ist, geben die beiden Tools, die die echte API aufrufen, einen klaren Fehler zurück:

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


Beispiel für Client-Konfiguration

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

Allgemeine Konfiguration für jeden Client, der stdio MCP unterstützt:

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

Tools im Detail

seedance_usage_guide

Keine Parameter. Gibt eine vollständige Anleitung im Markdown-Format zurück. Es wird empfohlen, dies vor dem ersten Aufruf von seedance_create_task einmal aufzurufen.

seedance_create_task

Reicht einen Videogenerierungsauftrag ein, gibt sofort task_id zurück.

Eingabeparameter:

Feld

Typ

Standard

Beschreibung

prompt

string

— (erforderlich)

Beschreibung in natürlicher Sprache. Bei Referenzmaterialien im Prompt mit [Image1] / [Video1] / [Audio1] referenzieren.

model

enum

doubao-seedance-2-0-260128

doubao-seedance-2-0-260128 (Standard, höchste Qualität) / doubao-seedance-2-0-fast-260128 (Schnell).

duration

integer

5

Videodauer in Sekunden. [4, 15].

ratio

enum

16:9

21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive.

resolution

enum

720p

480p oder 720p.

generate_audio

boolean

true

Ob synchrones Audio (Dialog / Soundeffekte / BGM) mitgeneriert werden soll.

watermark

boolean

true

Ob ein Plattform-Wasserzeichen hinzugefügt werden soll. Manche Konten können dies möglicherweise nicht deaktivieren.

web_search

boolean

false

Ob die Web-Suche für den Prompt aktiviert werden soll; nur bei reinem Texteingang verfügbar, kann nicht gleichzeitig mit image/video/audio verwendet werden.

return_last_frame

boolean

false

Ob die URL des letzten Frames für das Spleißen von Segmenten zurückgegeben werden soll.

image_urls

array

—

Maximal 9 Elemente; jedes { url, role? }, role ∈ reference_image / first_frame / last_frame, Standard reference_image.

video_urls

array

—

Maximal 3 Elemente; jedes { url, role? }, role ∈ reference_video.

audio_urls

array

—

Maximal 3 Elemente; jedes { url, role? }, role ∈ reference_audio. Muss mit image oder video kombiniert werden.

Validierungsregeln:

  • duration muss eine Ganzzahl zwischen [4, 15] sein.

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

  • Nur reiner Text + audio_urls wird abgelehnt (Seedance unterstützt dies nicht).

  • web_search=true zusammen mit Referenzmaterial wird abgelehnt (Web-Suche unterstützt nur reinen Text).

Rückgabe:

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

seedance_check_task

Eingabe { task_id: string }. Mögliche Status:

  • running / queued / pending — Wird noch verarbeitet. Bitte 30-90 Sekunden warten und erneut aufrufen.

  • succeeded — Gibt video_url zurück; falls return_last_frame=true, wird auch last_frame_url zurückgegeben.

  • failed — Gibt fail_reason zurück (falls vorhanden).

  • cancelled / expired — Auftrag wurde abgebrochen oder ist abgelaufen.

  • Andere — Gibt status und das ursprüngliche Payload unverändert zurück.


Typischer Aufrufablauf

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 内会过期)

Ein 15-Sekunden-Auftrag mit dem Standardmodell benötigt normalerweise 2-5 Minuten; die schnelle Version ist kürzer.


Sicherheitshinweise

  • Schreiben Sie den ARK_API_KEY nicht in das git-Repository. Platzieren Sie ihn im env-Feld der MCP-Client-Konfiguration (z. B. claude_desktop_config.json, ~/.codex/config.toml) oder in den Shell-Umgebungsvariablen.

  • Dieses Tool druckt den ARK_API_KEY nicht in Protokollen oder Rückgabewerten.

  • Die von Volcengine generierten video_url und last_frame_url sind signierte temporäre URLs, die laut offiziellen Angaben von Volcengine standardmäßig 24 Stunden gültig sind; bitte laden Sie die Dateien nach erfolgreichem Auftrag zeitnah herunter, um ein Ablaufen der Links zu vermeiden.

  • Die von Ihnen übergebenen image_urls / video_urls / audio_urls müssen öffentlich zugängliche HTTPS- (oder HTTP-) Adressen sein; lokale Pfade, interne Netzwerkadressen oder Ressourcen, die einen Login erfordern, können vom Volcengine-Server nicht abgerufen werden.

  • Bitte halten Sie sich an die Nutzungsbedingungen von Volcengine ARK und dem Seedance-Modell und generieren Sie keine illegalen, jugendgefährdenden oder urheberrechtsverletzenden Inhalte.


Entwicklung

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

Empfehlung für das Debugging von stdio MCP:

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

Oder lokaler Quellcode:

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

Projektstruktur

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

Lizenz

MIT © seedance-2-mcp contributors

Dieses Projekt hat keine offizielle Verbindung zu ByteDance, Volcengine oder Volcengine ARK. Die Namen "Seedance", "Doubao", "火山方舟" usw. sind Eigentum ihrer jeweiligen Inhaber.

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.

Inputs: task_id (required).

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.

Inputs: prompt (required), model, duration, ratio, +8 more.

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.

Inputs: no named parameters.

Tool Schema Changelog

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

Loading tool schema changelog…

    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.

    Related MCP Connectors

    Related MCP Servers