Seedance MCP

A local stdio MCP server that gives Codex and other MCP clients six tools for video generation: inspect models, upload reference images, submit jobs, query progress, download results, and check connectivity.

简体中文 · API mapping · Contributing

This is an independent adapter for the SeeDance-compatible API described below. It is not an official ByteDance, Seedance, or OpenAI project. The default API host (sd2.bantakal.com) is a third-party service; an official Seedance API key is not interchangeable with its dk_ keys. Check your provider's access terms and current pricing before submitting a job. This repository provides the adapter, not API access or model weights.

Requirements

• Node.js 22 or newer and npm.

• An account and dk_ API key from a compatible provider, required for authenticated operations.

• A local MCP client such as Codex. Server discovery works without an API key.

Related MCP server: MCP Server SimpleNGAT

Install from source

git clone https://github.com/xiao345/seedance-mcp.git
cd seedance-mcp
npm ci --ignore-scripts
node src/index.mjs --help

No compilation is required. Dependencies are locked in package-lock.json. Installation does not require a credential and does not generate videos. The project is distributed on GitHub; no npm registry installation is assumed.

Configure credentials

On macOS/Linux, create a private configuration file outside the repository:

mkdir -p "$HOME/.config/seedance-mcp"
chmod 700 "$HOME/.config/seedance-mcp"
cp -n .env.example "$HOME/.config/seedance-mcp/.env"
chmod 600 "$HOME/.config/seedance-mcp/.env"

Edit that file and set SEEDANCE_API_KEY to your provider's dk_ key. Do not paste keys into a chat, issue, or commit.

Environment variables take precedence over the file. Configuration is read on each tool call, so rotating a key does not require restarting the server. A .env file in the checkout is not automatically loaded. On Windows, the default is .config/seedance-mcp/.env under your user home; create it with your editor and restrict its filesystem permissions, or set SEEDANCE_CONFIG_FILE to a private location.

Connect to Codex

From the cloned directory, register absolute paths so desktop startup does not depend on your shell configuration:

codex mcp add seedance -- "$(command -v node)" "$PWD/src/index.mjs"

Then add startup_timeout_sec = 20 and tool_timeout_sec = 120 to the generated [mcp_servers.seedance] table in ~/.codex/config.toml. An equivalent manual configuration is:

[mcp_servers.seedance]
command = "/absolute/path/to/node"
args = ["/absolute/path/to/seedance-mcp/src/index.mjs"]
startup_timeout_sec = 20
tool_timeout_sec = 120

Replace both paths with your actual locations. On Windows, use paths such as C:/Program Files/nodejs/node.exe and C:/projects/seedance-mcp/src/index.mjs. Restart your client after adding a server. An already-open chat may need to be reopened. The CLI and desktop app share the configuration for the same Codex host; see the official Codex MCP documentation.

Other MCP clients can use the same command and args. For clients using mcpServers JSON:

{
  "mcpServers": {
    "seedance": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/seedance-mcp/src/index.mjs"]
    }
  }
}

If your client has a per-tool timeout, set it to at least 120 seconds for downloads. Video generation itself is asynchronous and returns immediately.

Tools

Defaults: seedance-2.0, 10 seconds, 9:16, 720p, no reference images. For the documented 2.0 model, durations are 10/15 seconds and reference images are limited to eight. seedance-2.5-30s, if enabled by the provider, requires duration: 30. Model availability and price come from seedance_list_models; they may change. Ratios are 9:16, 16:9, and 1:1.

Example request to your MCP client:

Use seedance to make a 10-second 16:9 video of a corgi running across grass, with a slow camera push-in. Keep the task ID, wait for completion, and download it to an absolute path I provide.

For image references, first upload local images, then pass their returned asset IDs in order. A prompt containing @Image2 needs at least two IDs. Images must be PNG/JPEG/WEBP, at most 5 MB each.

Job lifecycle and costs

1. Query the enabled models.

2. Optionally upload reference images.

3. Submit once and retain the task ID. Submission consumes provider credits.

4. Query every 10–20 seconds until succeeded, failed, or interrupted.

5. Download completed results promptly. The supplied provider documentation describes an upstream retention window of approximately 24 hours; do not rely on link expiry alone.

The server does not automatically retry POST requests or poll indefinitely inside a tool call. If submission times out, its outcome is unknown: check the provider's generation history before creating another job to avoid duplicate charges. Refund policy is controlled by the provider.

Verification and development

npm run check
npm run format:check
npm test
npm run verify
npm pack --dry-run

Tests use loopback HTTP fixtures and real MCP SDK clients, with no provider credentials or paid generation. npm run verify is offline: it checks the stdio handshake and tool catalog without Codex or an API call.

Optional read-only live checks:

npm run verify:live   # Local entry point: health + authenticated model list
npm run verify:codex  # Same checks using the command registered as seedance in Codex

These require network access and a configured provider key. They do not create videos. verify:codex additionally requires the Codex CLI and its existing server registration.

Data handling and limitations

Prompts, reference images, and API credentials are sent to your configured provider over HTTPS. Downloads write to the exact local path requested by the client. This is a local trusted-client service, not a sandbox: only connect trusted MCP clients and approve intended file operations. There is no telemetry or embedded credential in this adapter.

API requests have a 30-second deadline; downloads have a 90-second network deadline and a 512 MB limit. Downloads use temporary files and atomic no-overwrite publishing. Redirects are limited to five, HTTPS downgrade is refused, and API keys are removed on cross-origin redirects. Failed downloads remove partial files. Existing output files are never replaced.

To unregister from Codex: codex mcp remove seedance. This preserves the checkout and your private configuration file.

License

MIT. Provider access terms and generated-content rights are separate from this software license.