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:
git clone https://github.com/Doriandarko/sora-mcp
cd sora-mcp
- Install dependencies:
npm install
- Build the project:
npm run build
- Configure for Claude Desktop:
- Copy
claude_desktop_config.example.jsonto~/Library/Application Support/Claude/claude_desktop_config.json - Update the
argspath to match your installation directory - Add your OpenAI API key to the
OPENAI_API_KEYfield - Optionally set
DOWNLOAD_DIRto your preferred download folder
- Copy
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
.envfile 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:
npm run dev
Or in production mode:
npm run build
npm start
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:
{
"mcpServers": {
"sora-server": {
"command": "node",
"args": ["/ABSOLUTE/PATH/TO/sora-mcp/dist/stdio-server.js"],
"env": {
"OPENAI_API_KEY": "your-openai-api-key-here",
"DOWNLOAD_DIR": "/Users/yourname/Downloads/sora"
}
}
}
}
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:
npx @modelcontextprotocol/inspector
Then connect to: http://localhost:3000/mcp
Claude Code
claude mcp add --transport http sora-server http://localhost:3000/mcp
VS Code
code --add-mcp '{"name":"sora-server","type":"http","url":"http://localhost:3000/mcp"}'
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:
{
"prompt": "A calico cat playing a piano on stage",
"model": "sora-2",
"seconds": "8",
"size": "1024x1808"
}
get-video-status
Check the status and progress of a video generation job.
Parameters:
video_id(required): ID of the video to check
Example:
{
"video_id": "video_123"
}
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:
{
"limit": 10,
"order": "desc"
}
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:
{
"video_id": "video_123"
}
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:
{
"video_id": "video_123",
"filename": "my-cat-video.mp4"
}
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:
{
"video_id": "video_123",
"prompt": "Extend the scene with the cat taking a bow to the cheering audience"
}
delete-video
Delete a video job and its assets.
Parameters:
video_id(required): ID of the video to delete
Example:
{
"video_id": "video_123"
}
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
{
"id": "video_123",
"object": "video",
"model": "sora-2",
"status": "queued",
"progress": 0,
"created_at": 1712697600,
"size": "1024x1808",
"seconds": "8",
"quality": "standard"
}
Remix Response
{
"id": "video_456",
"object": "video",
"model": "sora-2",
"status": "queued",
"progress": 0,
"created_at": 1712698600,
"size": "720x1280",
"seconds": "8",
"remixed_from_video_id": "video_123"
}
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
sora-mcp/
├── src/
│ └── server.ts # Main server implementation
├── dist/ # Compiled JavaScript (generated)
├── package.json # Dependencies and scripts
├── tsconfig.json # TypeScript configuration
├── .env # Environment variables (not in git)
└── README.md # This file
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