Sora 2 MCP Server

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

npm install -g sora-2-mcp-server

Or use with npx (no installation required):

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):

{
  "mcpServers": {
    "sora-2": {
      "command": "npx",
      "args": ["-y", "sora-2-mcp-server"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key-here"
      }
    }
  }
}

Or if installed globally:

{
  "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:

{
  "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:

{
  "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:

{
  "limit": 10
}

4. delete_video

Delete a video generation job.

Parameters:

• video_id (required): ID of the video to delete

Example:

{
  "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:

{
  "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:

{
  "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

# 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