Sora MCP

🚀 Sora MCP Server

A Model Context Protocol (MCP) server that integrates with OpenAI's Sora 2 API for video generation and remixing.

🚀 Quick Start

The Sora MCP Server integrates with OpenAI's Sora 2 API, enabling video generation and remixing. Follow the steps below to get started.

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

📦 Installation

Prerequisites

• Node.js 18+
• OpenAI API key with Sora access
• An MCP-compatible client (Claude, Cursor, VS Code, etc.)

Steps

1. Clone the repository:

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

2. Install dependencies:

npm install

3. Build the project:

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.

🔧 Technical Details

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 Examples

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

📚 Documentation

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