Package Exports

@hamaster/sora2-mcp-server
@hamaster/sora2-mcp-server/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@hamaster/sora2-mcp-server) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Sora2 MCP Server

基于 Sora2 API 的 MCP (Model Context Protocol) 服务器，支持通过文字或图片生成高质量视频。

功能特性

文字生成视频：通过文本提示词生成视频
图片生成视频：基于参考图片生成视频
多种模型支持：支持 sora-2 基础版和 sora-2-pro 高级版
灵活的分辨率设置：支持多种视频分辨率（最高支持 1792x1024）
可配置的视频时长：支持 10秒、15秒、25秒三种时长
多种视频风格：支持动漫、漫画、新闻、复古等多种风格
MinIO 缓存集成：自动缓存生成的视频到 MinIO，提高访问速度

安装

前置要求

Node.js 18 或更高版本
npm 或 yarn 包管理器
Sora2 API 密钥

安装步骤

克隆或下载本项目：

git clone <repository-url>
cd sora2-mcp-server

安装依赖：

npm install

配置环境变量（详见下方配置说明）
测试运行：

npm start

环境变量配置

创建 .env 文件，参考 .env.example 文件配置以下环境变量：

必需配置

# Sora2 API 密钥（必需）
SORA2_API_KEY=sk-your-api-key-here

# Sora2 API 基础地址（可选，默认为 https://api.apiyi.com/v1/videos）
SORA2_BASE_URL=https://api.apiyi.com/v1/videos

可选配置（MinIO 缓存）

MinIO 用于缓存生成的视频，配置后可提高重复访问速度。

# MinIO 服务器地址
MINIO_ENDPOINT=your-minio-server.com

# MinIO 端口（默认为 9000）
MINIO_PORT=9000

# 是否使用 SSL（true/false，默认为 false）
MINIO_USE_SSL=false

# MinIO 访问密钥
MINIO_ACCESS_KEY=your-access-key

# MinIO 密钥
MINIO_SECRET_KEY=your-secret-key

# MinIO 存储桶名称（默认为 tmp）
MINIO_BUCKET=tmp

# MinIO 公开访问 URL（用于返回视频 URL）
MINIO_PUBLIC_URL=https://your-public-url.com

注意：如果不配置 MinIO，服务器仍然可以正常工作，但不会缓存视频。

使用方法

使用 npx 快速安装（推荐）

如果您已经将此包发布到 npm，可以直接使用 npx 快速安装和运行，无需手动克隆项目：

{
  "mcpServers": {
    "sora2": {
      "command": "npx",
      "args": [
        "-y",
        "@hamaster/sora2-mcp-server"
      ],
      "env": {
        "SORA2_API_KEY": "sk-your-api-key-here",
        "SORA2_BASE_URL": "https://api.apiyi.com/v1/videos",
        "MINIO_ENDPOINT": "cdn.hamaster.cn",
        "MINIO_PORT": "9000",
        "MINIO_USE_SSL": "false",
        "MINIO_ACCESS_KEY": "11333333333333",
        "MINIO_SECRET_KEY": "NK5iGmOZHheeqVEd69mueqXyIUrtWTMmNQdymWSS",
        "MINIO_BUCKET": "tmp",
        "MINIO_PUBLIC_URL": "https://cdn.deepix.hk"
      }
    }
  }
}

参数说明：

-y：自动确认安装，避免交互式提示
@hamaster/sora2-mcp-server：包名称（对应 package.json 中的 name 字段）

优点：

无需手动克隆和安装项目
自动使用最新版本
配置简单，只需指定包名

使用本地路径安装

如果您想使用本地开发版本或未发布到 npm 的版本，可以直接指定本地路径：

{
  "mcpServers": {
    "sora2": {
      "command": "node",
      "args": [
        "d:\\workspace\\MCPs\\sora2-mcp-server\\index.js"
      ],
      "env": {
        "SORA2_API_KEY": "sk-your-api-key-here",
        "SORA2_BASE_URL": "https://api.apiyi.com/v1/videos",
        "MINIO_ENDPOINT": "cdn.hamaster.cn",
        "MINIO_PORT": "9000",
        "MINIO_USE_SSL": "false",
        "MINIO_ACCESS_KEY": "11333333333333",
        "MINIO_SECRET_KEY": "NK5iGmOZHheeqVEd69mueqXyIUrtWTMmNQdymWSS",
        "MINIO_BUCKET": "tmp",
        "MINIO_PUBLIC_URL": "https://cdn.deepix.hk"
      }
    }
  }
}

配置步骤

打开 Claude Desktop 的配置文件：
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
根据您的需求选择上述两种配置方式之一（npx 或本地路径）添加到配置文件
重启 Claude Desktop

可用工具

1. submit_video_task

提交视频生成任务。

参数：

prompt（必需）：视频生成的提示词描述
imageUrl（可选）：输入图片的 URL 地址，不提供则为文字生成视频
model（可选）：模型名称
- sora-2：基础版（默认）
- sora-2-pro：高级版，支持更高分辨率和更长时长
size（可选）：视频分辨率
- sora-2 支持：1280x720、720x1280
- sora-2-pro 支持：1280x720、720x1280、1024x1792、1792x1024
- 默认值：1280x720
seconds（可选）：视频时长（秒）
- sora-2 支持：10、15
- sora-2-pro 支持：10、15、25
- 默认值：10
style（可选）：视频风格
- 可选值：thanksgiving(感恩节)、comic(漫画)、news(新闻)、selfie(自拍)、nostalgic(复古)、anime(动漫)
- 默认：无风格

示例：

文字生成视频：

请使用 sora2 工具生成一个视频：提示词为"一只可爱的猫咪在阳光下打滚"，模型使用 sora-2，分辨率 1280x720，时长 10 秒，风格为动漫。

图片生成视频：

请使用 sora2 工具生成一个视频：参考图片 URL 为 https://example.com/image.jpg，提示词为"让画面中的人物微笑"，模型使用 sora-2-pro，分辨率 1792x1024，时长 15 秒。

2. check_task_status

查询视频生成任务的状态和结果。

参数：

taskId（必需）：视频生成任务的 ID

示例：

请查询任务 ID "task_xxxxxx" 的状态。

返回状态说明：

submitted：任务已提交，等待处理
in_progress：视频生成中
completed：视频生成完成，返回视频 URL
failed：视频生成失败

使用流程

提交任务：使用 submit_video_task 工具提交视频生成请求
获取任务 ID：从返回结果中获取 taskId
等待处理：视频生成通常需要 3-5 分钟
查询状态：使用 check_task_status 工具定期查询任务进度
获取结果：任务完成后获取视频 URL

注意：如果配置了 MinIO，视频会自动缓存到 MinIO，后续查询相同任务时会直接返回缓存的视频 URL。

模型对比

特性	sora-2	sora-2-pro
分辨率	1280x720、720x1280	1280x720、720x1280、1024x1792、1792x1024
视频时长	10秒、15秒	10秒、15秒、25秒
描述	基础版模型	高级版模型，支持更高分辨率和更长时长

注意事项

视频 API 生成任务为异步处理，通常需要 3-5 分钟
建议定期（每 30-60 秒）查询任务状态，避免频繁调用
MinIO 配置是可选的，不配置不影响核心功能
确保环境变量中的 API 密钥安全，不要泄露
分辨率和时长参数必须与所选模型兼容，否则会报错

开发和测试

运行服务器

npm start

测试脚本

项目中包含 Python 演示脚本 sora2-demo.py，可用于测试 API 功能。

许可证

MIT

贡献

欢迎提交 Issue 和 Pull Request！