Integrates with OpenAI's Sora 2 API for video generation and remixing, allowing users to create videos from text prompts, remix existing videos, check generation status, and manage video assets.
Sora MCP Server
A Model Context Protocol (MCP) server that integrates with OpenAI's Sora 2 API for video generation and remixing.
Features
Create Videos: Generate videos from text prompts using Sora 2
Remix Videos: Create variations of existing videos with new prompts
Video Status: Check the status and progress of video generation jobs
Prerequisites
Node.js 18+
OpenAI API key with Sora access
An MCP-compatible client (Claude, Cursor, VS Code, etc.)
Installation
Clone the repository:
Install dependencies:
Build the project:
Configure for Claude Desktop:
Copy
claude_desktop_config.example.json
to~/Library/Application Support/Claude/claude_desktop_config.json
Update the
args
path to match your installation directoryAdd your OpenAI API key to the
OPENAI_API_KEY
fieldOptionally set
DOWNLOAD_DIR
to your preferred download folder
Server Architecture
This project includes two server implementations for different use cases:
š± stdio-server.ts
- For Claude Desktop
Transport: stdio (Standard Input/Output)
Use case: Local process communication
How it works: Claude Desktop spawns this as a child process
Benefits: Fast, secure, no network needed
Used by: Claude Desktop
š server.ts
- For Remote Access
Transport: HTTP/Streamable HTTP
Use case: Remote clients, web-based tools
How it works: Runs as HTTP server on port 3000
Benefits: Network accessible, multiple clients
Used by: MCP Inspector, VS Code, Cursor, browsers
Why two servers? Different MCP clients use different transports. This separation keeps the code clean and optimized for each transport type.
Usage
For Claude Desktop (stdio mode)
Claude Desktop will automatically start the server when configured. Just make sure:
Your
.env
file has yourOPENAI_API_KEY
Restart Claude Desktop after updating the config
The config uses src/stdio-server.ts
which communicates via stdio.
For HTTP Mode (MCP Inspector, web clients)
Run the server in development mode with auto-reload:
Or in production mode:
Connecting to MCP Clients
Claude Desktop
The server is already configured!
Setup:
The configuration is at: ~/Library/Application Support/Claude/claude_desktop_config.json
It uses the compiled server and passes your API key via environment variables:
See claude_desktop_config.example.json
for a complete example.
Environment Variables:
OPENAI_API_KEY
(required) - Your OpenAI API keyDOWNLOAD_DIR
(optional) - Custom download folder (defaults to ~/Downloads)
To use:
Restart Claude Desktop (Cmd+Q then relaunch)
The Sora tools will appear automatically!
MCP Inspector (for testing)
Test your server with the MCP Inspector:
Then connect to: http://localhost:3000/mcp
Claude Code
VS Code
Cursor
Add to your Cursor MCP settings with stdio transport (similar to Claude Desktop configuration above).
Available Tools
create-video
Generate a video from a text prompt.
Parameters:
prompt
(required): Text description of the video to generatemodel
(optional): Model to use (default: "sora-2")seconds
(optional): Video duration in seconds (default: "4")size
(optional): Resolution as "widthxheight" (default: "720x1280")input_reference
(optional): Path to reference image/video
Example:
get-video-status
Check the status and progress of a video generation job.
Parameters:
video_id
(required): ID of the video to check
Example:
Returns: Video status including progress
(0-100), status
(queued/processing/completed), and completion timestamps.
list-videos
List all your video generation jobs with pagination.
Parameters:
limit
(optional): Number of videos to retrieve (default: 20)after
(optional): Pagination cursor - get videos after this IDorder
(optional): Sort order "asc" or "desc" (default: "desc")
Example:
download-video
Get a curl command to manually download a completed video.
Parameters:
video_id
(required): ID of the video to downloadvariant
(optional): Which format to download (defaults to MP4)
Example:
Returns: Ready-to-use curl command with authentication for downloading the video.
save-video ā (Auto-Download)
Automatically download and save a completed video to your computer.
Parameters:
video_id
(required): ID of the video to saveoutput_path
(optional): Directory to save to (defaults to ~/Downloads)filename
(optional): Custom filename (defaults to video_id.mp4)
Example:
Returns: File path where video was saved. No manual commands needed!
remix-video
Create a remix of an existing video with a new prompt.
Parameters:
video_id
(required): ID of the completed video to remixprompt
(required): New text prompt for the remix
Example:
delete-video
Delete a video job and its assets.
Parameters:
video_id
(required): ID of the video to delete
Example:
Typical Workflow
Create a video ā Get back a
video_id
"Create a video of a sunset over mountains"Check status ā Monitor progress
"Check the status of video video_123"Save when ready ā Auto-download the video file
"Save video video_123"Claude will automatically download it to your Downloads folder!
Clean up ā Delete old videos
"Delete video video_123"
API Response Format
Video Job Response
Remix Response
Error Handling
The server includes comprehensive error handling:
Missing API key validation on startup
API error responses with detailed messages
Graceful error returns in tool responses
Development
Project Structure
Scripts
npm run dev
- Run in development mode with tsxnpm run build
- Compile TypeScript to JavaScriptnpm start
- Run compiled JavaScript
Environment Variables
OPENAI_API_KEY
(required) - Your OpenAI API keyPORT
(optional) - Server port (default: 3000)
License
MIT
Resources
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Integrates with OpenAI's Sora 2 API to generate, remix, and manage AI-generated videos from text prompts. Supports video creation, status monitoring, downloading, and remixing through natural language commands.