Sora MCP

🚀 Sora MCP 服務器

這是一個模型上下文協議（MCP）服務器，可與 OpenAI 的 Sora 2 API 集成，用於視頻生成和混音。

🚀 快速開始

Sora MCP 服務器集成了 OpenAI 的 Sora 2 API，可實現視頻生成和混音功能。使用前請確保滿足前置條件，並按照安裝步驟進行操作。

✨ 主要特性

• 創建視頻：使用 Sora 2 根據文本提示生成視頻。
• 視頻混音：根據新提示對現有視頻進行混音，創建變體。
• 視頻狀態查詢：檢查視頻生成任務的狀態和進度。

📦 安裝指南

前置條件

• Node.js 18+
• 具有 Sora 訪問權限的 OpenAI API 密鑰
• 兼容 MCP 的客戶端（Claude、Cursor、VS Code 等）

安裝步驟

1. 克隆倉庫：

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

2. 安裝依賴：

npm install

3. 構建項目：

npm run build

4. 為 Claude Desktop 進行配置：
   • 將 claude_desktop_config.example.json 複製到 ~/Library/Application Support/Claude/claude_desktop_config.json
   • 更新 args 路徑以匹配你的安裝目錄
   • 將你的 OpenAI API 密鑰添加到 OPENAI_API_KEY 字段
   • 可選擇將 DOWNLOAD_DIR 設置為你首選的下載文件夾

🔧 技術細節

服務器架構

本項目包含 兩個服務器實現，適用於不同的用例：

📱 stdio-server.ts - 用於 Claude Desktop

• 傳輸方式：stdio（標準輸入/輸出）
• 用例：本地進程通信
• 工作原理：Claude Desktop 將其作為子進程啟動
• 優點：快速、安全，無需網絡
• 使用場景：Claude Desktop

🌐 server.ts - 用於遠程訪問

• 傳輸方式：HTTP/可流式傳輸的 HTTP
• 用例：遠程客戶端、基於 Web 的工具
• 工作原理：在端口 3000 上作為 HTTP 服務器運行
• 優點：可通過網絡訪問，支持多個客戶端
• 使用場景：MCP Inspector、VS Code、Cursor、瀏覽器

為什麼有兩個服務器？ 不同的 MCP 客戶端使用不同的傳輸方式。這種分離使代碼更簡潔，並針對每種傳輸類型進行了優化。

💻 使用示例

針對 Claude Desktop（stdio 模式）

Claude Desktop 配置完成後將自動啟動服務器。請確保：

1. 你的 .env 文件中包含 OPENAI_API_KEY
2. 更新配置後重啟 Claude Desktop

配置使用 src/stdio-server.ts 通過 stdio 進行通信。

針對 HTTP 模式（MCP Inspector、Web 客戶端）

在開發模式下運行服務器並開啟自動重載：

npm run dev

或在生產模式下運行：

npm run build
npm start

連接到 MCP 客戶端

Claude Desktop

服務器已完成配置！ 設置步驟： 配置文件位於：~/Library/Application Support/Claude/claude_desktop_config.json 它使用編譯後的服務器，並通過環境變量傳遞你的 API 密鑰：

{
  "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"
      }
    }
  }
}

完整示例請參考 claude_desktop_config.example.json。 環境變量：

• OPENAI_API_KEY（必需） - 你的 OpenAI API 密鑰
• DOWNLOAD_DIR（可選） - 自定義下載文件夾（默認為 ~/Downloads） 使用方法：

1. 重啟 Claude Desktop（Cmd+Q 然後重新啟動）
2. Sora 工具將自動顯示！

MCP Inspector（用於測試）

使用 MCP Inspector 測試你的服務器：

npx @modelcontextprotocol/inspector

然後連接到：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

在你的 Cursor MCP 設置中添加 stdio 傳輸方式（類似於上面的 Claude Desktop 配置）。

可用工具

create-video

根據文本提示生成視頻。 參數：

• prompt（必需）：要生成視頻的文本描述
• model（可選）：使用的模型（默認："sora-2"）
• seconds（可選）：視頻時長（秒）（默認："4"）
• size（可選）：分辨率（格式為 "寬度x高度"）（默認："720x1280"）
• input_reference（可選）：參考圖像/視頻的路徑 示例：

{
  "prompt": "A calico cat playing a piano on stage",
  "model": "sora-2",
  "seconds": "8",
  "size": "1024x1808"
}

get-video-status

檢查視頻生成任務的狀態和進度。 參數：

• video_id（必需）：要檢查的視頻 ID 示例：

{
  "video_id": "video_123"
}

返回值：視頻狀態，包括 progress（0 - 100）、status（排隊/處理中/已完成）和完成時間戳。

list-videos

分頁列出所有視頻生成任務。 參數：

• limit（可選）：要檢索的視頻數量（默認：20）
• after（可選）：分頁遊標 - 獲取此 ID 之後的視頻
• order（可選）：排序順序（"asc" 或 "desc"）（默認："desc"） 示例：

{
  "limit": 10,
  "order": "desc"
}

download-video

獲取一個 curl 命令，用於手動下載已完成的視頻。 參數：

• video_id（必需）：要下載的視頻 ID
• variant（可選）：要下載的格式（默認為 MP4） 示例：

{
  "video_id": "video_123"
}

返回值：帶有認證信息的可直接使用的 curl 命令，用於下載視頻。

save-video ⭐（自動下載）

自動下載並將已完成的視頻保存到你的計算機。 參數：

• video_id（必需）：要保存的視頻 ID
• output_path（可選）：保存目錄（默認為 ~/Downloads）
• filename（可選）：自定義文件名（默認為 video_id.mp4） 示例：

{
  "video_id": "video_123",
  "filename": "my-cat-video.mp4"
}

返回值：視頻保存的文件路徑。無需手動命令！

remix-video

根據新提示對現有視頻進行混音。 參數：

• video_id（必需）：要混音的已完成視頻的 ID
• prompt（必需）：混音的新文本提示 示例：

{
  "video_id": "video_123",
  "prompt": "Extend the scene with the cat taking a bow to the cheering audience"
}

delete-video

刪除視頻任務及其資產。 參數：

• video_id（必需）：要刪除的視頻 ID 示例：

{
  "video_id": "video_123"
}

典型工作流程

1. 創建視頻 → 獲取 video_id

"Create a video of a sunset over mountains"

2. 檢查狀態 → 監控進度

"Check the status of video video_123"

3. 準備好後保存 → 自動下載視頻文件

"Save video video_123"

Claude 將自動將其下載到你的下載文件夾！ 4. 清理 → 刪除舊視頻

"Delete video video_123"

📚 詳細文檔

API 響應格式

視頻任務響應

{
  "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"
}

錯誤處理

服務器包含全面的錯誤處理：

• 啟動時對缺失的 API 密鑰進行驗證
• 帶有詳細消息的 API 錯誤響應
• 工具響應中優雅地返回錯誤

開發

項目結構

sora-mcp/
├── src/
│   └── server.ts       # 主服務器實現
├── dist/               # 編譯後的 JavaScript（自動生成）
├── package.json        # 依賴項和腳本
├── tsconfig.json       # TypeScript 配置
├── .env               # 環境變量（不包含在 git 中）
└── README.md          # 本文件

腳本

• npm run dev - 使用 tsx 在開發模式下運行
• npm run build - 將 TypeScript 編譯為 JavaScript
• npm start - 運行編譯後的 JavaScript

環境變量

• OPENAI_API_KEY（必需） - 你的 OpenAI API 密鑰
• PORT（可選） - 服務器端口（默認：3000）

📄 許可證

本項目採用 MIT 許可證。

資源

• 模型上下文協議文檔
• OpenAI Sora API 文檔
• MCP TypeScript SDK