Which integrations are available for this server?

Enables AI video generation using the Sora model, allowing users to create videos from text or images, maintain character consistency across scenes, and customize output orientations and durations.

MCP Sora

PyPI version PyPI downloads

PyPI version PyPI downloads Python 3.10+ License: MIT MCP

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, portrait, and square videos
Task Tracking - Monitor generation progress and retrieve results

Quick Start

1. Get API Token

Get your API token from AceDataCloud Platform:

Sign up or log in
Navigate to Sora Videos API
Click "Acquire" to get your token

2. Install

# Clone the repository
git clone https://github.com/AceDataCloud/mcp-sora.git
cd mcp-sora

# Install with pip
pip install -e .

# Or with uv (recommended)
uv pip install -e .

3. Configure

# Copy example environment file
cp .env.example .env

# Edit with your API token
echo "ACEDATACLOUD_API_TOKEN=your_token_here" > .env

4. Run

# Run the server
mcp-sora

# Or with Python directly
python main.py

Claude Desktop Integration

Add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "sora": {
      "command": "mcp-sora",
      "env": {
        "ACEDATACLOUD_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Or if using uv:

{
  "mcpServers": {
    "sora": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-sora", "mcp-sora"],
      "env": {
        "ACEDATACLOUD_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Remote HTTP Mode (Hosted)

AceDataCloud hosts a managed MCP server that you can connect to directly — no local installation required.

Endpoint: https://sora.mcp.acedata.cloud/mcp

All requests require a Bearer token in the Authorization header. Get your token from AceDataCloud Platform.

Claude Desktop (Remote)

{
  "mcpServers": {
    "sora": {
      "type": "streamable-http",
      "url": "https://sora.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer your_api_token_here"
      }
    }
  }
}

Cursor / VS Code

In your MCP client settings, add:

Type: streamable-http
URL: https://sora.mcp.acedata.cloud/mcp
Headers: Authorization: Bearer your_api_token_here

cURL Test

# Health check (no auth required)
curl https://sora.mcp.acedata.cloud/health

# MCP initialize (requires Bearer token)
curl -X POST https://sora.mcp.acedata.cloud/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer your_api_token_here" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

Self-Hosting with Docker

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 and uses it for upstream API calls.

Available Tools

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

Information

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 generation
large - Higher resolution (recommended)

Orientation:

landscape - 16:9 (YouTube, presentations)
portrait - 9:16 (TikTok, Instagram Stories)
square - 1:1 (Instagram posts)

Duration:

10 seconds - All models
15 seconds - All models
25 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`
`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

# Clone repository
git clone https://github.com/AceDataCloud/mcp-sora.git
cd mcp-sora

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # or `.venv\Scripts\activate` on Windows

# Install with dev dependencies
pip install -e ".[dev,test]"

Run Tests

# Run unit tests
pytest

# Run with coverage
pytest --cov=core --cov=tools

# Run integration tests (requires API token)
pytest tests/test_integration.py -m integration

Code Quality

# Format code
ruff format .

# Lint code
ruff check .

# Type check
mypy core tools

Build & Publish

# Install build dependencies
pip install -e ".[release]"

# Build package
python -m build

# Upload to PyPI
twine upload dist/*

Project Structure

MCPSora/
├── 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

API Reference

This server wraps the AceDataCloud Sora API:

Sora Videos API - Video generation
Sora Tasks API - Task queries

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