@hamaster/sora2-mcp-server

v1.0.4

Published

18 days ago

MCP Server for Sora2 image-to-video generation

0High
0Medium
0Low

hamaster

mcp sora2 video-generation image-to-video

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！