Sora MCP Server

Sora MCP服务器

模型上下文协议（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

1. 安装依赖项：

npm install

1. 构建项目：

npm run build

1. 为Claude桌面配置：

- 复制 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将此作为子进程生成
• 优点： 快速、安全、无需网络
• 使用人： 克劳德桌面版

🌐 server.ts -用于远程访问

• 运输： HTTP/可流式传输HTTP
• 使用案例： 远程客户端、基于网络的工具
• 它是如何工作的： 在端口3000上作为HTTP服务器运行
• 优点： 网络可访问，多个客户端
• 使用人： MCP检查器、VS代码、游标、浏览器

为什么是两台服务器？ 不同的MCP客户端使用不同的传输方式。这种分离使代码保持干净，并针对每种传输类型进行了优化。

用法

适用于克劳德桌面（stdio模式）

配置后，Claude Desktop将自动启动服务器。只要确保：

1. 你的 .env 文件有你的 OPENAI_API_KEY
2. 更新配置后重新启动Claude Desktop

配置使用 src/stdio-server.ts 它通过stdio进行通信。

对于HTTP模式（MCP检查器、web客户端）

在开发模式下运行服务器并自动重新加载：

npm run dev

或者在生产模式下：

npm run build
npm start

连接到MCP客户端

克劳德桌面版

服务器已配置！

设置： 配置位于： ~/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. 重新启动克劳德桌面（Cmd+Q，然后重新启动）
2. Sora工具将自动出现！

MCP检查员（用于测试）

使用MCP检查器测试您的服务器：

npx @modelcontextprotocol/inspector

然后连接到： http://localhost:3000/mcp

克劳德代码

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

光标

使用stdio传输添加到光标MCP设置中（类似于上面的Claude Desktop配置）。

可用工具

创建视频

从文本提示生成视频。

参数：

• prompt （必填）：要生成的视频的文本描述
• model （可选）：要使用的模型（默认值：“sora-2”）
• seconds （可选）：视频持续时间（秒）（默认值：“4”）
• size （可选）：分辨率为“widthxheight”（默认值：“720x1280”）
• input_reference （可选）：参考图像/视频的路径

例子：

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

获取视频状态

检查视频生成作业的状态和进度。

参数：

• video_id （必填）：要检查的视频ID

例子：

{
  "video_id": "video_123"
}

退货： 视频状态包括 progress (0-100), status （排队/处理/完成）和完成时间戳。

列出视频

列出所有带分页的视频生成作业。

参数：

• limit （可选）：要检索的视频数量（默认值：20）
• after （可选）：分页光标-获取此ID后的视频
• order （可选）：排序顺序“asc”或“desc”（默认：“desc“）

例子：

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

下载视频

获取curl命令以手动下载完成的视频。

参数：

• video_id （必填）：要下载的视频的ID
• variant （可选）：下载哪种格式（默认为MP4）

例子：

{
  "video_id": "video_123"
}

退货： 已准备好使用带有身份验证的curl命令下载视频。

保存视频⭐ （自动下载）

自动下载并将完成的视频保存到您的计算机。

参数：

• video_id （必填）：要保存的视频的ID
• output_path （可选）：要保存的目录（默认为~/Downloads）
• filename （可选）：自定义文件名（默认为video_id.mp4）

例子：

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

退货： 保存视频的文件路径。无需手动命令！

混音视频

使用新提示创建现有视频的混音。

参数：

• video_id （必填）：要重新混音的已完成视频的ID
• prompt （必填）：混音的新文本提示

例子：

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

删除视频

删除视频作业及其资源。

参数：

• video_id （必填）：要删除的视频的ID

例子：

{
  "video_id": "video_123"
}

典型工作流程

1. 创建视频 → 回来a video_id

   "Create a video of a sunset over mountains"

1. 检查状态 → 监督进展

   "Check the status of video video_123"

1. 准备就绪后保存 → 自动下载视频文件

   "Save video video_123"

Claude会自动将其下载到您的下载文件夹中！

1. 清理 → 删除旧视频

   "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       # 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

脚本

• npm run dev -使用tsx在开发模式下运行
• npm run build -将TypeScript编译为JavaScript
• npm start -运行编译的JavaScript

环境变量

• OPENAI_API_KEY （必需）-您的OpenAI API密钥
• PORT （可选）-服务器端口（默认值：3000）

许可证

麻省理工学院

资源

• 模型上下文协议文档
• OpenAI Sora API文档
• MCP TypeScript SDK