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ツール

ツール	役割
`seedance_usage_guide`	完全な使用ガイド（標準フロー、モデル選択、パラメータ表、注意事項）を返します。
`seedance_create_task`	Seedance 2.0動画生成タスクを送信し、。
`seedance_check_task`	`task_id` を使用してタスクの状態を確認し、成功時に `video_url` とオプションの最終フレーム画像を返します。

詳細なパラメータは Toolsの詳細を参照してください。

ローカルエージェント向けのクイック接続プロンプト

Codex、Claude Desktop、CursorなどのMCP対応ローカルエージェントを使用している場合、このリポジトリのリンクを直接送信し、以下のセクションを読ませることができます。

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

また、エージェントに対して直接次のように指示することもできます：

このリポジトリを読み、READMEの「ローカルエージェント向けのクイック接続プロンプト」に従って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`	はい	火山エンジンARKのAPIキー。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を実際に呼び出す2つのツールは明確なエラーを返します：

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	—（必須）	自然言語による記述。参照素材がある場合は、プロンプト内で `[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`	プロンプトに対してWeb検索による強化を有効にするか。純粋なテキスト入力でのみ使用可能。画像/動画/音声と同時に使用不可。
`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 と参照素材を同時に指定すると拒否されます（Web検索強化は純粋なテキストのみサポート）。

戻り値：

{
  "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 を出力しません。
火山エンジンが生成する video_url および last_frame_url は 署名付きの一時URL であり、火山エンジンの公式仕様に基づきデフォルトで24時間有効です。タスク完了後は速やかにダウンロードし、リンク切れを防いでください。
指定する image_urls / video_urls / audio_urls はすべて パブリックアクセス可能な HTTPS（またはHTTP）アドレスである必要があります。ローカルパス、イントラネットアドレス、ログインが必要なリソースは火山エンジンのサーバーから取得できません。
火山エンジンおよび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

ライセンス

本プロジェクトは、ByteDance、火山エンジン、Volcengine ARKとは 公式な関連はありません。「Seedance」、「Doubao」、「火山エンジン」などの名称の著作権はそれぞれの所有者に帰属します。

seedance-2-mcp

seedance-2-mcp

提供されるMCPツール

ローカルエージェント向けのクイック接続プロンプト

インストール

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ツール

ローカルエージェント向けのクイック接続プロンプト

インストール

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`