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:

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

1. Install dependencies:

npm install

1. Build the project:

npm run build

1. 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:

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

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

{
  "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 ID
• order (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 download
• variant (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 save
• output_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 remix
• prompt (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

1. Create a video → Get back a video_id

   "Create a video of a sunset over mountains"
   

2. Check status → Monitor progress

   "Check the status of video video_123"
   

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

   "Save video video_123"
   

   Claude will automatically download it to your Downloads folder!

4. 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 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