Sora2 MCP

🎬 Demo Video

昭和レトロCM風デモ動画を生成しました！

Video ID: video_68e4f09ad79c8198a43196de75bbe1b10170aa9f31b5a6a2

🎨 スタイル: 1960年代日本のTV CM風
⏱️ 長さ: 4秒
📐 解像度: 1280x720
🤖 モデル: sora-2

このデモは、Sora2 MCPを使って自動生成された昭和初期カラーTV時代のレトロなコマーシャル風の動画です。

The Universal MCP Server exposes tools for OpenAI's Sora API, enabling programmatic creation, management, and remixing of AI-generated videos. Designed for prompt-first usage in MCP-compatible clients.

Installation

Prerequisites

Node.js 18+
Set SORA2_MCP_API_KEY (or OPENAI_API_KEY) in your environment

Get an API key

Obtain your OpenAI API key from OpenAI Platform
Ensure your account has access to the Sora API (currently in limited beta)
For more information, see the Sora API documentation

Build locally

cd /path/to/sora2-mcp
npm i
npm run build

Setup: Claude Code (CLI)

Use this one-liner (replace with your real values):

claude mcp add sora2-mcp -s user -e SORA2_MCP_API_KEY="sk-your-real-key" -- npx sora2-mcp

To remove:

claude mcp remove sora2-mcp

Setup: Cursor

Note: This repository does not include .cursor/mcp.json. Configure Cursor via its UI settings, or create .cursor/mcp.json in your client workspace (do not commit it here):

{
  "mcpServers": {
    "sora2-mcp": {
      "command": "npx",
      "args": ["sora2-mcp"],
      "env": {
        "SORA2_MCP_API_KEY": "sk-your-real-key"
      },
      "autoStart": true
    }
  }
}

Other Clients and Agents

VS Code

Install via CLI:

code --add-mcp '{"name":"sora2-mcp","command":"npx","args":["sora2-mcp"],"env":{"SORA2_MCP_API_KEY":"sk-your-real-key"}}'

Or configure in your VS Code settings under MCP servers.

VS Code Insiders

Similar to VS Code, use the Insiders binary:

code-insiders --add-mcp '{"name":"sora2-mcp","command":"npx","args":["sora2-mcp"],"env":{"SORA2_MCP_API_KEY":"sk-your-real-key"}}'

Claude Desktop

Add to your Claude Desktop MCP configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "sora2-mcp": {
      "command": "npx",
      "args": ["sora2-mcp"],
      "env": {
        "SORA2_MCP_API_KEY": "sk-your-real-key"
      }
    }
  }
}

Restart Claude Desktop after saving.

LM Studio

In LM Studio's MCP settings:

Command: npx
Args: ["sora2-mcp"]
Environment Variables:
- SORA2_MCP_API_KEY = sk-your-real-key

Goose

Configure in Goose's MCP settings:

Type: STDIO
Command: npx
Args: sora2-mcp
Enabled: true

Add environment variable SORA2_MCP_API_KEY in your shell or Goose config.

opencode

Example ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sora2-mcp": {
      "type": "local",
      "command": ["npx", "sora2-mcp"],
      "env": {
        "SORA2_MCP_API_KEY": "sk-your-real-key"
      },
      "enabled": true
    }
  }
}

Qodo Gen

Add a new MCP server in Qodo Gen settings and paste the standard JSON config:

{
  "name": "sora2-mcp",
  "command": "npx",
  "args": ["sora2-mcp"],
  "env": {
    "SORA2_MCP_API_KEY": "sk-your-real-key"
  }
}

Windsurf

Configure in Windsurf's MCP settings. Reuse the standard config above with command npx and args ["sora2-mcp"].

Setup: Codex (TOML)

Add the following to your Codex TOML configuration.

Example (Serena reference):

[mcp_servers.serena]
command = "uvx"
args = ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "codex"]

This server (minimal):

[mcp_servers.sora2-mcp]
command = "npx"
args = ["sora2-mcp"]
# Optional environment variables:
# SORA2_MCP_API_KEY = "sk-your-real-key"
# MCP_NAME = "sora2-mcp"

Configuration (Env)

SORA2_MCP_API_KEY (or OPENAI_API_KEY): Your OpenAI API key with Sora access
MCP_NAME: Server name override (default: sora2-mcp)

Available Tools

`create_video`

Start a new video generation job with Sora. Returns a job object with status. Poll get_video_status or use webhooks to monitor completion.

Inputs:
- prompt (string, required): Text description of the video. Be specific about shot type, subject, action, setting, and lighting for best results.
- model (string, optional): Model to use. "sora-2" (faster for iteration) or "sora-2-pro" (higher quality for production). Default: "sora-2"
- size (string, optional): Video resolution. Options: "1280x720", "1920x1080", "720x1280", "1080x1920". Default: "1280x720"
- seconds (string, optional): Video duration. Options: "4", "8", "12". Default: "8"
- input_reference (string, optional): Base64-encoded image (JPEG, PNG, or WebP) to use as the first frame. Must match target resolution.
Outputs: JSON object with id, status (queued, in_progress, completed, failed), progress, and other metadata.

`get_video_status`

Retrieve the current status and progress of a video generation job.

Inputs:
- video_id (string, required): The video job ID returned from create_video
Outputs: JSON object with status, progress percentage, and metadata.

`download_video`

Download the completed video file (MP4), thumbnail (WebP), or spritesheet (JPEG). Only works when status is completed. Returns base64-encoded binary data.

Inputs:
- video_id (string, required): The video job ID
- variant (string, optional): What to download. Options: "video" (MP4), "thumbnail" (WebP), "spritesheet" (JPEG). Default: "video"
Outputs: JSON object with video_id, variant, size_bytes, data_base64, and usage notes.

`list_videos`

List all video jobs with pagination support. Returns metadata for enumeration, dashboards, or housekeeping.

Inputs:
- limit (number, optional): Number of videos to return. Default: 10, Max: 100
- after (string, optional): Cursor for pagination to fetch the next page
- order (string, optional): Sort order by creation date. Options: "asc", "desc". Default: "desc"
Outputs: JSON object with data array of video objects and pagination metadata.

`delete_video`

Delete a video from OpenAI's storage. This action is permanent.

Inputs:
- video_id (string, required): The video job ID to delete
Outputs: Confirmation JSON object.

`remix_video`

Create a new video by remixing an existing completed video with targeted adjustments. Preserves structure and composition while applying modifications.

Inputs:
- video_id (string, required): The ID of the completed video to use as the base
- prompt (string, required): Description of the change to apply. Keep it focused on a single, well-defined adjustment for best results.
Outputs: JSON object with new job id and status.

For detailed input/output schemas, see src/index.ts.

Example Invocation (MCP Tool Call)

{
  "name": "create_video",
  "arguments": {
    "prompt": "Wide tracking shot of a teal coupe driving through a desert highway, heat ripples visible, hard sun overhead.",
    "model": "sora-2-pro",
    "size": "1280x720",
    "seconds": "8"
  }
}

Response:

{
  "id": "video_68d7512d07848190b3e45da0ecbebcde004da08e1e0678d5",
  "object": "video",
  "created_at": 1758941485,
  "status": "queued",
  "model": "sora-2-pro",
  "progress": 0,
  "seconds": "8",
  "size": "1280x720"
}

Then poll with:

{
  "name": "get_video_status",
  "arguments": {
    "video_id": "video_68d7512d07848190b3e45da0ecbebcde004da08e1e0678d5"
  }
}

Once status is "completed", download with:

{
  "name": "download_video",
  "arguments": {
    "video_id": "video_68d7512d07848190b3e45da0ecbebcde004da08e1e0678d5",
    "variant": "video"
  }
}

Troubleshooting

401 authentication errors: Check that SORA2_MCP_API_KEY (or OPENAI_API_KEY) is set correctly and that your account has Sora API access.
Ensure Node 18+: Run node -v to verify your Node.js version.
Local runs: After building with npm run build, test locally with npx . or node build/index.js in the project directory.
Inspect publish artifacts: Run npm pack --dry-run to see what files will be published.
Video generation takes time: Depending on model and resolution, rendering may take several minutes. Use polling or webhooks to monitor progress efficiently.
Download URLs expire: Video download URLs are valid for a maximum of 24 hours. Save files promptly to your own storage.
Content restrictions: The API enforces guardrails (no copyrighted characters, no real people, etc.). Ensure prompts and inputs comply.

References

Name Consistency & Troubleshooting

Always use CANONICAL_ID (sora2-mcp) for identifiers and keys.
Use CANONICAL_DISPLAY (Sora2 MCP) only for UI labels.
Do not mix different names across clients.

Consistency Matrix

Context	Value
npm package name	`sora2-mcp`
Binary name	`sora2-mcp`
MCP server name (SDK metadata)	`sora2-mcp`
Env default `MCP_NAME`	`sora2-mcp`
Client registry key	`sora2-mcp`
UI label	`Sora2 MCP`

Conflict Cleanup

Remove any old entries (e.g., legacy display names like "Sora2") from your MCP configuration and re-add with "sora2-mcp" as the key.
Ensure global .mcp.json or client registries only use "sora2-mcp" for keys.
Cursor: Configure in the UI only. This project does not include .cursor/mcp.json.

Example

Correct:

{
  "mcpServers": {
    "sora2-mcp": {
      "command": "npx",
      "args": ["sora2-mcp"]
    }
  }
}

Incorrect:

{
  "mcpServers": {
    "Sora2": {
      "command": "npx",
      "args": ["sora2-mcp"]
    }
  }
}

Using inconsistent keys like "Sora2" will conflict with "sora2-mcp".

License

MIT