Seedance / Seedream MCP

Python MCP server for BytePlus Seedream 5.0 Pro, Seedance 2.0, TOS media staging, and the private portrait asset library. It is designed for local verification first and deployment as a Native Python 3.11 Web Application on BytePlus veFaaS.

Runtime shape

• Streamable HTTP MCP endpoint: POST /mcp
• Health endpoint: GET /health
• Upload widget: GET /widget/
• Upload API: POST /api/uploads
• Redis-backed short-lived sessions
• Shared TOS bucket and shared BytePlus credentials for v1

Setup

Create a virtual environment, install dependencies, and copy the environment template:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt
cp .env.example .env

On PowerShell:

py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements-dev.txt
Copy-Item .env.example .env

Fill every required value in .env. Startup fails immediately when any required value is missing.

Run locally

bash run.sh

or:

python -m uvicorn app.main:app --host 127.0.0.1 --port 8000

Verify:

curl http://127.0.0.1:8000/health
python scripts/smoke_mcp.py http://127.0.0.1:8000/mcp

Tools

Planning tools never call generation APIs:

• creative_plan_launch_set
• creative_resolve_video_preset

Media and reference state:

• media_start_upload_session
• media_finalize_upload_session
• media_get_upload_session
• media_import_generated_asset

Generation and portrait preparation:

• seedream_generate_image
• seedance_generate_video
• seedance_prepare_portrait_asset
• seedance_get_portrait_asset_status

Task control and diagnostics:

• generation_get_task
• generation_list_tasks
• generation_cancel_task
• system_get_runtime_config
• system_validate_byteplus_connectivity

system_get_runtime_config masks ARK_API_KEY, BYTEPLUS_AK, BYTEPLUS_SK, and the optional BYTEPLUS_SESSION_TOKEN.

Main workflows

Seedream image

1. Optionally stage reference images and finalize the upload session.
2. Call seedream_generate_image.
3. Reuse the returned reference_session_id directly with Seedance. Outputs generated by ModelArk are trusted and do not need private-asset conversion.

Normal media to Seedance

1. Create an upload session with workflow_type=normal.
2. Upload to the returned TOS PUT URLs.
3. Finalize the session.
4. Pass its reference_session_id to seedance_generate_video.

User-uploaded portrait to Seedance

1. Create an upload session with workflow_type=portrait.
2. Upload and finalize.
3. Call seedance_prepare_portrait_asset.
4. When the asset is Active, pass the returned asset://... as an image_url content item to seedance_generate_video.

The user is responsible for having the legal rights and authorization required to use uploaded real-person media.

Tests

python -m pytest -q

The default suite uses mocks and requires no production credentials. Tests cover config validation, secret masking, schemas, planning helpers, upload state, provider adapters, MCP tool discovery, and MCP initialize.

Live integration calls are intentionally not part of the default suite because they consume provider quota and require configured BytePlus resources.

Claude Desktop local verification

Claude Desktop can reach the Streamable HTTP server through a local bridge:

{
  "mcpServers": {
    "seedance-seedream": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8000/mcp"
      ]
    }
  }
}

Restart Claude Desktop, confirm tool discovery, then try:

1. Create a 2K JPEG product hero image with Seedream.
2. Open the upload flow for a normal image, then animate it with Seedance.
3. Open the portrait upload flow, prepare the private asset, wait until it is Active, then create a five-second 9:16 video.

Expected results are structured tool outputs containing reference session IDs, provider task IDs, asset URIs when active, and suggested next actions.

See DEPLOY.md for veFaaS and API Gateway deployment.