SeedanceMCP
A Model Context Protocol (MCP) server for AI video generation using ByteDance Seedance through the AceDataCloud API.
Generate AI videos directly from Claude, VS Code, or any MCP-compatible client.
Features
- Text to Video - Create AI-generated videos from text prompts
- Image to Video - Animate images with first frame, last frame, and reference image control
- Multiple Models - Support for Seedance 2.0 (incl. Fast/Mini, multimodal reference), 1.5 Pro, 1.0 Pro, 1.0 Pro Fast, 1.0 Lite T2V/I2V
- Multiple Resolutions - 480p, 720p (default), 1080p, and 4k output (2.5 supports 1080p; 4k:
doubao-seedance-2-0-260128 only)
- Flexible Aspect Ratios - 16:9, 9:16, 1:1, 4:3, 3:4, 21:9, and adaptive
- Audio Generation - Generate synchronized audio for videos (1.5 Pro and 2.0 series)
- Service Tiers - Default (priority) and Flex (cost-effective) processing
- Task Tracking - Monitor generation progress and retrieve results
| Tool | Description |
|---|
seedance_generate_video | Generate AI video from a text prompt using ByteDance Seedance. |
seedance_generate_video_from_image | Generate AI video using reference images with ByteDance Seedance. |
seedance_get_task | Query the status and result of a video generation task. |
seedance_get_tasks_batch | Query multiple video generation tasks at once. |
seedance_list_models | List all available Seedance models with their capabilities and pricing. |
seedance_list_resolutions | List all available resolutions and aspect ratios for Seedance. |
seedance_list_actions | List all available Seedance API actions and corresponding tools. |
Quick Start
1. Get Your API Token
- Sign up at AceDataCloud Platform
- Go to the API documentation page
- Click "Acquire" to get your API token
- Copy the token for use below
2. Use the Hosted Server (Recommended)
AceDataCloud hosts a managed MCP server — no local installation required.
Endpoint: https://seedance.mcp.acedata.cloud/mcp
All requests require a Bearer token. Use the API token from Step 1.
Claude.ai
Connect directly on Claude.ai with OAuth — no API token needed:
- Go to Claude.ai Settings → Integrations → Add More
- Enter the server URL:
https://seedance.mcp.acedata.cloud/mcp
- Complete the OAuth login flow
- Start using the tools in your conversation
Claude Desktop
Add to your config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"seedance": {
"type": "streamable-http",
"url": "https://seedance.mcp.acedata.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN"
}
}
}
}
Cursor / Windsurf
Add to your MCP config (.cursor/mcp.json or .windsurf/mcp.json):
{
"mcpServers": {
"seedance": {
"type": "streamable-http",
"url": "https://seedance.mcp.acedata.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN"
}
}
}
}
VS Code (Copilot)
Add to your VS Code MCP config (.vscode/mcp.json):
{
"servers": {
"seedance": {
"type": "streamable-http",
"url": "https://seedance.mcp.acedata.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN"
}
}
}
}
Or install the Ace Data Cloud MCP extension for VS Code, which registers the hosted MCP servers with one-click setup.
JetBrains IDEs
- Go to Settings → Tools → AI Assistant → Model Context Protocol (MCP)
- Click Add → HTTP
- Paste:
{
"mcpServers": {
"seedance": {
"url": "https://seedance.mcp.acedata.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN"
}
}
}
}
Claude Code
Claude Code supports MCP servers natively:
claude mcp add seedance --transport http https://seedance.mcp.acedata.cloud/mcp \
-h "Authorization: Bearer YOUR_API_TOKEN"
Or add to your project's .mcp.json:
{
"mcpServers": {
"seedance": {
"type": "streamable-http",
"url": "https://seedance.mcp.acedata.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN"
}
}
}
}
Cline
Add to Cline's MCP settings (.cline/mcp_settings.json):
{
"mcpServers": {
"seedance": {
"type": "streamable-http",
"url": "https://seedance.mcp.acedata.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN"
}
}
}
}
Amazon Q Developer
Add to your MCP configuration:
{
"mcpServers": {
"seedance": {
"type": "streamable-http",
"url": "https://seedance.mcp.acedata.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN"
}
}
}
}
Roo Code
Add to Roo Code MCP settings:
{
"mcpServers": {
"seedance": {
"type": "streamable-http",
"url": "https://seedance.mcp.acedata.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN"
}
}
}
}
Continue.dev
Add to .continue/config.yaml:
mcpServers:
- name: seedance
type: streamable-http
url: https://seedance.mcp.acedata.cloud/mcp
headers:
Authorization: "Bearer YOUR_API_TOKEN"
Zed
Add to Zed's settings (~/.config/zed/settings.json):
{
"language_models": {
"mcp_servers": {
"seedance": {
"url": "https://seedance.mcp.acedata.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN"
}
}
}
}
}
cURL Test
curl https://seedance.mcp.acedata.cloud/health
curl -X POST https://seedance.mcp.acedata.cloud/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
3. Or Run Locally (Alternative)
If you prefer to run the server on your own machine:
pip install mcp-seedance
uvx mcp-seedance
export ACEDATACLOUD_API_TOKEN="your_token_here"
mcp-seedance
mcp-seedance --transport http --port 8000
Claude Desktop (Local)
{
"mcpServers": {
"seedance": {
"command": "uvx",
"args": ["mcp-seedance"],
"env": {
"ACEDATACLOUD_API_TOKEN": "your_token_here"
}
}
}
}
Docker (Self-Hosting)
docker pull ghcr.io/acedatacloud/mcp-seedance:latest
docker run -p 8000:8000 ghcr.io/acedatacloud/mcp-seedance:latest
Clients connect with their own Bearer token — the server extracts the token from each request's Authorization header.
Video Generation
| Tool | Description |
|---|
seedance_generate_video | Generate video from a text prompt |
seedance_generate_video_from_image | Generate video using reference/start/end images |
Tasks
| Tool | Description |
|---|
seedance_get_task | Query a single task status |
seedance_get_tasks_batch | Query multiple tasks at once |
| Tool | Description |
|---|
seedance_list_models | List available Seedance models |
seedance_list_resolutions | List available output resolutions |
seedance_list_actions | List available API actions |
Usage Examples
Generate Video from Prompt
User: Create a video of a cat playing with a ball of yarn
Claude: I'll generate a video for you.
[Calls seedance_generate_video with prompt="A cute cat playfully batting a ball of yarn"]
Animate an Image
User: Turn this image into a video: https://example.com/landscape.jpg
Claude: I'll create a video from your image.
[Calls seedance_generate_video_from_image with first_frame_url and appropriate prompt]
Generate with Audio
User: Create a video of rain falling with sound
Claude: I'll generate a video with synchronized audio.
[Calls seedance_generate_video with prompt="Rain falling on a quiet street" and generate_audio=True, model="doubao-seedance-1-5-pro-251215"]
Available Models
| Model | Description | Features |
|---|
doubao-seedance-2-5-260628 | 2.5 | Up to 30s and 1080p, edit/extend, multimodal reference |
doubao-seedance-2-0-fast-260128 | 2.0 Fast | Latest generation fast |
doubao-seedance-2-0-mini-260615 | 2.0 Mini | Latest generation, lightweight, cheapest 2.0 |
doubao-seedance-1-5-pro-251215 | 1.5 Pro | Audio generation, T2V, I2V |
doubao-seedance-1-0-pro-250528 | 1.0 Pro | High quality T2V, I2V |
doubao-seedance-1-0-pro-fast-251015 | 1.0 Pro Fast | Faster generation |
doubao-seedance-1-0-lite-t2v-250428 | 1.0 Lite T2V | Lightweight text-to-video |
doubao-seedance-1-0-lite-i2v-250428 | 1.0 Lite I2V | Lightweight image-to-video |
Available Aspect Ratios
| Aspect Ratio | Description | Use Case |
|---|
16:9 | Landscape (default) | YouTube, TV, presentations |
9:16 | Portrait | TikTok, Instagram Reels |
1:1 | Square | Instagram posts |
4:3 | Traditional | Classic video format |
3:4 | Portrait traditional | Portrait content |
21:9 | Ultrawide | Cinematic content |
adaptive | Adaptive | Auto-detect from image |
Configuration
Environment Variables
| Variable | Description | Default |
|---|
ACEDATACLOUD_API_TOKEN | API token from AceDataCloud | Required |
ACEDATACLOUD_API_BASE_URL | API base URL | https://api.acedata.cloud |
ACEDATACLOUD_OAUTH_CLIENT_ID | OAuth client ID (hosted mode) | — |
ACEDATACLOUD_PLATFORM_BASE_URL | Platform base URL | https://platform.acedata.cloud |
SEEDANCE_DEFAULT_MODEL | Default model | doubao-seedance-2-0-260128 |
SEEDANCE_DEFAULT_RESOLUTION | Default resolution | 720p |
SEEDANCE_DEFAULT_RATIO | Default aspect ratio | 16:9 |
SEEDANCE_DEFAULT_DURATION | Default duration (seconds) | 5 |
SEEDANCE_REQUEST_TIMEOUT | Request timeout in seconds | 1800 |
LOG_LEVEL | Logging level | INFO |
Command Line Options
mcp-seedance --help
Options:
--version Show version
--transport Transport mode: stdio (default) or http
--port Port for HTTP transport (default: 8000)
Development
Setup Development Environment
git clone https://github.com/AceDataCloud/SeedanceMCP.git
cd SeedanceMCP
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,test]"
Run Tests
pytest
pytest --cov=core --cov=tools
pytest tests/test_integration.py -m integration
Code Quality
ruff format .
ruff check .
mypy core tools
Build & Publish
pip install -e ".[release]"
python -m build
twine upload dist/*
Project Structure
SeedanceMCP/
├── core/ # Core modules
│ ├── __init__.py
│ ├── client.py # HTTP client for Seedance API
│ ├── config.py # Configuration management
│ ├── exceptions.py # Custom exceptions
│ ├── server.py # MCP server initialization
│ ├── types.py # Type definitions
│ └── utils.py # Utility functions
├── tools/ # MCP tool definitions
│ ├── __init__.py
│ ├── video_tools.py # Video generation tools
│ ├── task_tools.py # Task query tools
│ └── info_tools.py # Information tools
├── prompts/ # MCP prompts
│ └── __init__.py # Prompt templates
├── tests/ # Test suite
│ ├── conftest.py
│ ├── test_client.py
│ ├── test_config.py
│ ├── test_integration.py
│ └── test_utils.py
├── deploy/ # Deployment configs
│ └── production/
│ ├── deployment.yaml
│ ├── ingress.yaml
│ └── service.yaml
├── .env.example # Environment template
├── .gitignore
├── CHANGELOG.md
├── Dockerfile # Docker image for HTTP mode
├── docker-compose.yaml # Docker Compose config
├── LICENSE
├── main.py # Entry point
├── pyproject.toml # Project configuration
└── README.md
API Reference
This server wraps the AceDataCloud Seedance API:
Contributing
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing)
- Commit your changes (
git commit -m 'Add amazing feature')
- Push to the branch (
git push origin feature/amazing)
- Open a Pull Request
Documentation
Documentation
License
MIT License - see LICENSE for details.
Links
Made with love by AceDataCloud