Sora Video MCP Server

MCP server for generating videos using the Sora AI API. Supports both text-to-video and image-to-video generation.

Features

• Text-to-Video Generation: Create videos from detailed text descriptions
• Image-to-Video Generation: Animate images with text prompts
• Status Tracking: Check video generation progress and retrieve download URLs
• Multiple Input Formats: Supports image URLs, Base64 strings, and local file paths
• Flexible Configuration: Customize orientation, duration, resolution, and model

Installation

# Clone or navigate to the project directory
cd sora-video-mcp-server

# Install dependencies
npm install

# Build the TypeScript code
npm run build

Configuration

Create a .env file in the project root with your Sora API credentials:

# Required: Your Sora API key
SORA_API_KEY=your-api-key-here

# Optional: API base URL (default: https://gptproto.com)
SORA_API_URL=https://gptproto.com

# Optional: Video output directory (default: ./videos)
VIDEO_OUTPUT_DIR=./videos

# Optional: Request timeout in milliseconds (default: 600000 = 10 minutes)
SORA_REQUEST_TIMEOUT=600000

See .env.example for a template.

Usage

Running the Server

# Start the MCP server
npm start

# Or run in development mode with auto-reload
npm run dev

Available Tools

1. sora_create_video_from_text

Generate a video from a text description.

Parameters:

• prompt (string, required): Detailed video description (10-2000 characters)
• model (string, optional): Model to use (default: "sora-2")
• orientation (string, optional): "portrait" or "landscape" (default: "landscape")
• duration (number, optional): 10, 15, or 25 seconds (default: 15)
• size (string, optional): "small" or "large" (default: "small")

Example:

{
  "prompt": "A majestic horse galloping across a sunlit meadow at golden hour, cinematic style",
  "orientation": "landscape",
  "duration": 15,
  "size": "small"
}

2. sora_get_video_status

Check the status of a video generation task.

Parameters:

• task_id (string, required): Task ID from video creation
• response_format (string, optional): "markdown" or "json" (default: "markdown")

Example:

{
  "task_id": "sora-2:task_01k6fbyvt0f22v8jfah10d96kc",
  "response_format": "markdown"
}

3. sora_create_video_from_image

Generate a video from an image with text description.

Parameters:

• prompt (string, required): How to animate the image
• input_image (string, required): Image URL, Base64 string, or local file path
• model (string, optional): Model to use (default: "sora-2")
• orientation (string, optional): "portrait" or "landscape" (default: "landscape")
• duration (number, optional): 10, 15, or 25 seconds (default: 15)
• size (string, optional): "small" or "large" (default: "small")

Example:

{
  "prompt": "Make the horse start running with wind blowing through its mane",
  "input_image": "./my-horse-image.jpg",
  "duration": 15
}

Video Generation Workflow

1. Create a video task using sora_create_video_from_text or sora_create_video_from_image
2. Receive a task ID in the response
3. Wait 5-10 minutes for video generation to complete
4. Check status using sora_get_video_status with the task ID
5. Download the video from the URL provided when status is "completed"

Important Notes:

• Video generation typically takes 5-10 minutes
• Video URLs expire after 24 hours
• The API may timeout during generation, but the task continues processing
• Check status periodically to get the final video URL

Video Specifications

Orientations

• Portrait: 9:16 aspect ratio (vertical video)
• Landscape: 16:9 aspect ratio (horizontal video)

Resolutions

• Small: 704×1280 pixels
• Large: 1792×1024 pixels

Durations

• 10 seconds
• 15 seconds (default)
• 25 seconds

Supported Image Formats

• JPEG/JPG
• PNG
• GIF
• WebP
• BMP

Error Handling

The server provides clear, actionable error messages:

• 401 Unauthorized: Invalid API key - check your .env file
• 403 Forbidden: Account doesn't have Sora API access
• 429 Rate Limited: Too many requests - wait before retrying
• 404 Not Found: Task ID invalid or expired (tasks expire after 24 hours)
• Timeout: Video still processing - check status later with task ID

Development

# Install dependencies
npm install

# Run in development mode with auto-reload
npm run dev

# Build TypeScript to JavaScript
npm run build

# Clean build artifacts
npm run clean

Project Structure

sora-video-mcp-server/
├── src/
│   ├── index.ts              # Main entry point
│   ├── types.ts              # TypeScript type definitions
│   ├── constants.ts          # Configuration and constants
│   ├── schemas/
│   │   └── video.ts          # Zod validation schemas
│   ├── services/
│   │   ├── api.ts            # Sora API client
│   │   └── image.ts          # Image processing utilities
│   └── tools/
│       ├── createVideoFromText.ts
│       ├── createVideoFromImage.ts
│       └── getVideoStatus.ts
├── dist/                     # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
├── .env                      # Your configuration (create this)
├── .env.example              # Configuration template
└── README.md

Requirements

• Node.js >= 18
• npm or yarn
• Sora API key

License

MIT

Support

For issues with:

• This MCP server: Open an issue in the repository
• Sora API: Contact the Sora API provider
• MCP protocol: See https://modelcontextprotocol.io

Contributing

Contributions welcome! Please ensure:

• TypeScript compiles without errors (npm run build)
• Code follows existing style and structure
• All tools have comprehensive descriptions and error handling