# Sora 2 MCP Server
[](https://www.npmjs.com/package/sora-2-mcp-server)
[](https://opensource.org/licenses/MIT)
Model Context Protocol (MCP) server for OpenAI's Sora 2 video generation API. Generate professional AI videos, merge clips, and create fade animations directly from Claude Code or any MCP-compatible client.
## Features
- **Video Generation**: Create videos from text prompts using Sora 2 or Sora 2 Pro
- **Video Merging**: Concatenate multiple video files using FFmpeg
- **Fade Animations**: Create fade in/out/in-out effects from static images
- **Status Monitoring**: Monitor video generation progress in real-time
- **Job Management**: List and delete video generation jobs
- **Flexible Parameters**: Control resolution (720p to 4K), duration (4-12s), and model selection
## Prerequisites
- Node.js 18+
- OpenAI API key with Sora 2 access
- Verified organization on OpenAI platform (required for Sora access)
- FFmpeg (optional, for video merging and fade animation features)
## Installation
```bash
npm install -g sora-2-mcp-server
```
Or use with npx (no installation required):
```bash
npx sora-2-mcp-server
```
## Configuration
### Add to Claude Code
Add this server to your Claude Code MCP settings (`~/.config/claude-code/mcp_settings.json`):
```json
{
"mcpServers": {
"sora-2": {
"command": "npx",
"args": ["-y", "sora-2-mcp-server"],
"env": {
"OPENAI_API_KEY": "your-openai-api-key-here"
}
}
}
}
```
Or if installed globally:
```json
{
"mcpServers": {
"sora-2": {
"command": "sora-2-mcp-server",
"env": {
"OPENAI_API_KEY": "your-openai-api-key-here"
}
}
}
}
```
## Available Tools
### 1. create_video
Generate a video using Sora 2 or Sora 2 Pro.
**Parameters:**
- `prompt` (required): Text description of the video
- `model` (optional): "sora-2" or "sora-2-pro" (default: "sora-2")
- `size` (optional): Resolution - "1280x720", "720x1280", "1792x1024", or "1024x1792" (default: "1280x720")
- `seconds` (optional): Duration - "4", "8", or "12" (default: "8")
**Example:**
```typescript
{
"prompt": "A serene sunset over a mountain lake with gentle waves",
"model": "sora-2-pro",
"size": "1792x1024",
"seconds": "12"
}
```
### 2. get_video_status
Check the status of a video generation job.
**Parameters:**
- `video_id` (required): ID of the video generation job
**Example:**
```typescript
{
"video_id": "vid_abc123"
}
```
### 3. list_videos
List all video generation jobs.
**Parameters:**
- `limit` (optional): Maximum number of videos to return (default: 20)
- `after` (optional): Cursor for pagination
**Example:**
```typescript
{
"limit": 10
}
```
### 4. delete_video
Delete a video generation job.
**Parameters:**
- `video_id` (required): ID of the video to delete
**Example:**
```typescript
{
"video_id": "vid_abc123"
}
```
### 5. merge_videos
Concatenate multiple video files into a single seamless video using FFmpeg.
**Parameters:**
- `video_urls` (required): Array of video file paths or URLs to merge (in order)
- `output_path` (optional): Path where the merged video will be saved (default: "merged_video.mp4")
**Example:**
```typescript
{
"video_urls": [
"/path/to/intro.mp4",
"/path/to/main_content.mp4",
"/path/to/outro.mp4"
],
"output_path": "final_video.mp4"
}
```
**Note:** Requires FFmpeg to be installed on your system.
### 6. create_fade_animation
Transform static images into dynamic video clips with professional fade effects.
**Parameters:**
- `image_path` (required): Path or URL to the input image
- `duration` (optional): Duration of the fade animation in seconds (default: 3)
- `output_path` (optional): Path where the video will be saved (default: "fade_animation.mp4")
- `fade_type` (optional): Type of fade effect - "in", "out", or "in-out" (default: "in")
**Example:**
```typescript
{
"image_path": "/path/to/logo.png",
"duration": 3,
"fade_type": "in-out",
"output_path": "logo_animation.mp4"
}
```
**Fade types:**
- **"in"**: Fade from black to full visibility
- **"out"**: Fade from full visibility to black
- **"in-out"**: Fade in, hold, then fade out
**Note:** Requires FFmpeg to be installed on your system.
## Usage with Claude Code
Once configured, you can use the Sora 2 tools directly in Claude Code:
```
Generate a video of a cat playing piano in a jazz club
```
Claude Code will automatically use the `create_video` tool to generate the video.
## API Access Notes
- Sora 2 API requires organization verification at platform.openai.com/settings/organization/general
- After verification, it can take up to 15 minutes for access to propagate
- Pricing (as of 2025-10-09):
- Sora 2: $0.10-0.20/second
- Sora 2 Pro: $0.30-0.50/second
## Development
```bash
# Watch mode for development
npm run watch
# Build for production
npm run build
```
## Troubleshooting
### "Organization not verified" error
1. Go to platform.openai.com/settings/organization/general
2. Click "Verify Organization"
3. Wait up to 15 minutes for access to propagate
### API endpoint errors
The Sora 2 API may still be in beta. Ensure your OpenAI account has access to the Sora 2 models through the web interface at sora.com before using the API.
## License
MIT
