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

1. Clone the repository:

bashCopy code
git clone https://github.com/Doriandarko/sora-mcp
cd sora-mcp

2. Install dependencies:

bashCopy code
npm install

3. Build the project:

bashCopy code
npm run build

4. 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 directory
   • Add your OpenAI API key to the OPENAI_API_KEY field
   • Optionally 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:

1. Your .env file has your OPENAI_API_KEY
2. 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:

bashCopy code
npm run dev

Or in production mode:

bashCopy code
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:

jsonCopy code
{
  "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 key
• DOWNLOAD_DIR (optional) - Custom download folder (defaults to ~/Downloads)

To use:

1. Restart Claude Desktop (Cmd+Q then relaunch)
2. The Sora tools will appear automatically!

MCP Inspector (for testing)

Test your server with the MCP Inspector:

bashCopy code
npx @modelcontextprotocol/inspector

Then connect to: http://localhost:3000/mcp

Claude Code

bashCopy code
claude mcp add --transport http sora-server http://localhost:3000/mcp

VS Code

bashCopy 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 generate
• model (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:

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

javascriptCopy code
{
  "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 ID
• order (optional): Sort order "asc" or "desc" (default: "desc")

Example:

javascriptCopy code
{
  "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 download
• variant (optional): Which format to download (defaults to MP4)

Example:

javascriptCopy code
{
  "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 save
• output_path (optional): Directory to save to (defaults to ~/Downloads)
• filename (optional): Custom filename (defaults to video_id.mp4)

Example:

javascriptCopy code
{
  "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 remix
• prompt (required): New text prompt for the remix

Example:

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

javascriptCopy code
{
  "video_id": "video_123"
}

Typical Workflow

1. Create a video → Get back a video_id

   Copy code
   "Create a video of a sunset over mountains"
   

2. Check status → Monitor progress

   Copy code
   "Check the status of video video_123"
   

3. Save when ready → Auto-download the video file

   Copy code
   "Save video video_123"
   

   Claude will automatically download it to your Downloads folder!

4. Clean up → Delete old videos

   Copy code
   "Delete video video_123"
   

API Response Format

Video Job Response

jsonCopy code
{
  "id": "video_123",
  "object": "video",
  "model": "sora-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1712697600,
  "size": "1024x1808",
  "seconds": "8",
  "quality": "standard"
}

Remix Response

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

Copy code
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 tsx
• npm run build - Compile TypeScript to JavaScript
• npm start - Run compiled JavaScript

Environment Variables

• OPENAI_API_KEY (required) - Your OpenAI API key
• PORT (optional) - Server port (default: 3000)

License

MIT

Resources

• Model Context Protocol Documentation
• OpenAI Sora API Documentation
• MCP TypeScript SDK