SoraMCP
Status: This MCP integration is retired and is no longer actively offered.
A Model Context Protocol (MCP) server for AI video generation using Sora through the AceDataCloud API.
Generate AI videos directly from Claude, VS Code, or any MCP-compatible client.
Features
- Text-to-Video - Generate videos from text descriptions
- Image-to-Video - Animate images and create videos from reference images
- Character Videos - Reuse characters across different scenes
- Async Generation - Webhook callbacks for production workflows
- Multiple Orientations - Landscape and portrait videos
- Task Tracking - Monitor generation progress and retrieve results
| Tool | Description |
|---|
sora_generate_video | Generate an AI video from a text prompt using Sora. |
sora_generate_video_from_image | Generate an AI video from reference images using Sora (Image-to-Video). |
sora_generate_video_with_character | Generate an AI video featuring a character from a reference video. |
sora_generate_video_async | Generate an AI video asynchronously with callback notification. |
sora_generate_video_v2 | Generate an AI video using Sora Version 2 (partner channel). |
sora_generate_video_v2_async | Generate an AI video asynchronously using Sora Version 2 with callback. |
sora_get_task | Query the status and result of a video generation task. |
sora_get_tasks_batch | Query multiple video generation tasks at once. |
sora_list_models | List all available Sora models and their capabilities. |
sora_list_actions | List all available Sora API actions and corresponding tools. |
Quick Start
1. Get Your API Token
- Sign in to AceDataCloud Platform
- Open Applications and copy an existing API token
2. Use the Hosted Server (Recommended)
AceDataCloud hosts a managed MCP server — no local installation required.
Endpoint: https://sora.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://sora.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": {
"sora": {
"type": "streamable-http",
"url": "https://sora.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": {
"sora": {
"type": "streamable-http",
"url": "https://sora.mcp.acedata.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN"
}
}
}
}
VS Code (Copilot)
Add to your VS Code MCP config (.vscode/mcp.json):
{
"servers": {
"sora": {
"type": "streamable-http",
"url": "https://sora.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": {
"sora": {
"url": "https://sora.mcp.acedata.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN"
}
}
}
}
Claude Code
Claude Code supports MCP servers natively:
claude mcp add sora --transport http https://sora.mcp.acedata.cloud/mcp \
-h "Authorization: Bearer YOUR_API_TOKEN"
Or add to your project's .mcp.json:
{
"mcpServers": {
"sora": {
"type": "streamable-http",
"url": "https://sora.mcp.acedata.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN"
}
}
}
}
Cline
Add to Cline's MCP settings (.cline/mcp_settings.json):
{
"mcpServers": {
"sora": {
"type": "streamable-http",
"url": "https://sora.mcp.acedata.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN"
}
}
}
}
Amazon Q Developer
Add to your MCP configuration:
{
"mcpServers": {
"sora": {
"type": "streamable-http",
"url": "https://sora.mcp.acedata.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN"
}
}
}
}
Roo Code
Add to Roo Code MCP settings:
{
"mcpServers": {
"sora": {
"type": "streamable-http",
"url": "https://sora.mcp.acedata.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN"
}
}
}
}
Continue.dev
Add to .continue/config.yaml:
mcpServers:
- name: sora
type: streamable-http
url: https://sora.mcp.acedata.cloud/mcp
headers:
Authorization: "Bearer YOUR_API_TOKEN"
Zed
Add to Zed's settings (~/.config/zed/settings.json):
{
"language_models": {
"mcp_servers": {
"sora": {
"url": "https://sora.mcp.acedata.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN"
}
}
}
}
}
cURL Test
curl https://sora.mcp.acedata.cloud/health
curl -X POST https://sora.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-sora
uvx mcp-sora
export ACEDATACLOUD_API_TOKEN="your_token_here"
mcp-sora
mcp-sora --transport http --port 8000
Claude Desktop (Local)
{
"mcpServers": {
"sora": {
"command": "uvx",
"args": ["mcp-sora"],
"env": {
"ACEDATACLOUD_API_TOKEN": "your_token_here"
}
}
}
}
Docker (Self-Hosting)
docker pull ghcr.io/acedatacloud/mcp-sora:latest
docker run -p 8000:8000 ghcr.io/acedatacloud/mcp-sora:latest
Clients connect with their own Bearer token — the server extracts the token from each request's Authorization header.
Video Generation
| Tool | Description |
|---|
sora_generate_video | Generate video from a text prompt |
sora_generate_video_from_image | Generate video from reference images |
sora_generate_video_with_character | Generate video with a character from reference video |
sora_generate_video_async | Generate video with callback notification |
Tasks
| Tool | Description |
|---|
sora_get_task | Query a single task status |
sora_get_tasks_batch | Query multiple tasks at once |
| Tool | Description |
|---|
sora_list_models | List available Sora models |
sora_list_actions | List available API actions |
Usage Examples
Generate Video from Prompt
User: Create a video of a sunset over mountains
Claude: I'll generate a sunset video for you.
[Calls sora_generate_video with prompt="A beautiful sunset over mountains..."]
Generate from Image
User: Animate this image of a city skyline
Claude: I'll bring this image to life.
[Calls sora_generate_video_from_image with image_urls and prompt]
Character-based Video
User: Use the robot character in a new scene
Claude: I'll create a new scene with the robot character.
[Calls sora_generate_video_with_character with character_url and prompt]
Available Models
| Model | Max Duration | Quality | Features |
|---|
sora-2 | 15 seconds | Good | Standard generation |
sora-2-pro | 25 seconds | Best | Higher quality, longer videos |
Video Options
Size:
small - Lower resolution, faster generationlarge - Higher resolution (recommended)
Orientation:
landscape - 16:9 (YouTube, presentations)portrait - 9:16 (TikTok, Instagram Stories)
Duration:
10 seconds - All models15 seconds - All models25 seconds - sora-2-pro only
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 |
SORA_DEFAULT_MODEL | Default model | sora-2 |
SORA_DEFAULT_SIZE | Default video size | large |
SORA_DEFAULT_DURATION | Default duration (seconds) | 15 |
SORA_DEFAULT_ORIENTATION | Default orientation | landscape |
SORA_REQUEST_TIMEOUT | Request timeout (seconds) | 3600 |
LOG_LEVEL | Logging level | INFO |
Command Line Options
mcp-sora --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/SoraMCP.git
cd SoraMCP
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
SoraMCP/
├── core/ # Core modules
│ ├── __init__.py
│ ├── client.py # HTTP client for Sora 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 prompt templates
│ └── __init__.py
├── 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
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
License
MIT License - see LICENSE for details.
Links
Made with love by AceDataCloud