# Sora 2 MCP Server

[![NPM Version](https://img.shields.io/npm/v/sora-2-mcp-server)](https://www.npmjs.com/package/sora-2-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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