STARWARCLOUD STARWAR.AI
返回市场
天空-MCP

天空-MCP

作者：Doriandarko197 星标更新：2025-10-09
安装使用来源：spider==github.com

项目介绍

Sora MCP 服务器

这是一个与 OpenAI 的 Sora 2 API 集成的 Model Context Protocol (MCP) 服务器，用于视频生成和混音。

特性

  • 创建视频：使用 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 Desktop：
    • 将 claude_desktop_config.example.json 复制到 ~/Library/Application Support/Claude/claude_desktop_config.json
    • 更新 args 路径以匹配您的安装目录
    • 在 OPENAI_API_KEY 字段中添加您的 OpenAI API 密钥
    • 可选地设置 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

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

可用工具

create-video

从文本提示生成视频。

参数：

  • prompt（必需）：要生成的视频的文字描述
  • model（可选）：使用的模型（默认："sora-2"）
  • seconds（可选）：视频时长（秒，默认："4"）
  • size（可选）：分辨率（"宽度x高度"，默认："720x1280"）
  • input_reference（可选）：参考图像/视频的路径

示例：

{
  "prompt": "一只花斑猫在舞台上弹钢琴",
  "model": "sora-2",
  "seconds": "8",
  "size": "1024x1808"
}

get-video-status

检查视频生成任务的状态和进度。

参数：

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

示例：

{
  "video_id": "video_123"
}

返回值： 包括 progress（0-100）、status（queued/processing/completed）以及完成时间戳的视频状态。

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": "扩展场景，让猫向欢呼的观众鞠躬"
}

delete-video

删除视频任务及其资源。

参数：

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

示例：

{
  "video_id": "video_123"
}

典型工作流程

  1. 创建视频 → 返回一个 video_id

    "创建一个日落山脉的视频"

  2. 检查状态 → 监控进度

    "检查视频 video_123 的状态"

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

    "保存视频 video_123"

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

  4. 清理 → 删除旧视频

    "删除视频 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

资源