A Model Context Protocol (MCP) server that integrates with OpenAI's Sora 2 API for video generation and remixing.
- 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
- Node.js 18+
- OpenAI API key with Sora access
- An MCP-compatible client (Claude, Cursor, VS Code, etc.)
- 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
This project includes two server implementations for different use cases:
- 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
- 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.
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.
Run the server in development mode with auto-reload:
npm run devOr in production mode:
npm run build
npm startThe 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!
Test your server with the MCP Inspector:
npx @modelcontextprotocol/inspectorThen connect to: http://localhost:3000/mcp
claude mcp add --transport http sora-server http://localhost:3000/mcpcode --add-mcp '{"name":"sora-server","type":"http","url":"http://localhost:3000/mcp"}'Add to your Cursor MCP settings with stdio transport (similar to Claude Desktop configuration above).
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"
}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 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"
}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.
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!
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 a video job and its assets.
Parameters:
video_id(required): ID of the video to delete
Example:
{
"video_id": "video_123"
}-
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"
{
"id": "video_123",
"object": "video",
"model": "sora-2",
"status": "queued",
"progress": 0,
"created_at": 1712697600,
"size": "1024x1808",
"seconds": "8",
"quality": "standard"
}{
"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"
}The server includes comprehensive error handling:
- Missing API key validation on startup
- API error responses with detailed messages
- Graceful error returns in tool responses
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
npm run dev- Run in development mode with tsxnpm run build- Compile TypeScript to JavaScriptnpm start- Run compiled JavaScript
OPENAI_API_KEY(required) - Your OpenAI API keyPORT(optional) - Server port (default: 3000)
MIT