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