airsulG/sora-mcp

Sora MCP Server

一个使用 OpenAI Sora 模型生成视频的 MCP (Model Context Protocol) 服务器。通过 api.tu-zi.com 官方格式接口调用 Sora 视频生成 API。

什么是 MCP？
Model Context Protocol (MCP) 是一个开放协议，允许 AI 助手（如 Claude、Cursor）与外部工具和数据源无缝交互。通过 MCP，AI 可以调用你的工具函数，实现更强大的功能。

功能特性

• 🎬 文本生成视频：通过自然语言描述生成高质量视频
• 📐 多种宽高比：支持竖屏（9:16）和横屏（16:9）视频
• 🌏 中英文提示词：支持中文和英文提示词
• ⏱️ 异步任务模式：自动提交任务、轮询状态、下载视频
• 📁 自动路径管理：自动创建输出目录，支持绝对路径和相对路径
• 📊 详细日志：通过 MCP Context 提供实时操作日志
• 🔒 安全可靠：使用环境变量管理 API 密钥，完善的错误处理

文件结构

sora-mcp/
├── server.py              # MCP 服务器主逻辑
├── pyproject.toml         # 项目配置和依赖声明
├── .env.example           # 环境变量模板
├── .gitignore             # Git 忽略规则
└── README.md              # 项目文档（本文件）

快速开始

1. 环境准备

系统要求：

• Python >= 3.11
• uv 包管理器（推荐）

获取 API 密钥：

• 联系 api.tu-zi.com 服务商获取 Sora API 密钥

2. 安装依赖

# 进入项目目录
cd sora-mcp

# 创建虚拟环境
uv venv

# 安装依赖
uv pip install -e .

3. 配置 API 密钥

# 复制环境变量模板
cp .env.example .env

# 编辑 .env 文件，填入你的 API 密钥
# SORA_API_KEY=your_actual_api_key_here

4. 启动 MCP 服务器

# 直接运行
python server.py

# 或使用安装的命令
sora-mcp

5. 配置 Cursor 或 Claude Desktop

方式 A：Cursor MCP 配置（推荐）

配置文件位置：

• macOS/Linux: ~/.cursor/mcp.json
• Windows: %USERPROFILE%\.cursor\mcp.json

配置内容：

{
  "mcpServers": {
    "sora-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/sora-mcp",
        "run",
        "server.py"
      ]
    }
  }
}

⚠️ 注意事项：

1. 将 /absolute/path/to/sora-mcp 替换为你的实际项目路径
2. 路径必须使用绝对路径（不支持 ~ 或相对路径）
3. 修改配置后需要重启 Cursor
4. 重启后在右下角工具栏查看 MCP 连接状态

如何获取绝对路径：

# 进入项目目录
cd sora-mcp

# 显示绝对路径
pwd
# 示例输出：/Users/username/projects/sora-mcp

方式 B：Claude Desktop 配置

配置文件位置：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

配置内容：

{
  "mcpServers": {
    "sora-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/sora-mcp",
        "run",
        "server.py"
      ]
    }
  }
}

同样需要将路径替换为实际的绝对路径。

使用说明

🎬 工具：generate_video

根据文本描述生成视频并保存到指定路径。

参数说明

使用示例

示例 1：生成竖屏视频

"生成一个视频：一只可爱的橘猫在阳光下行走，保存为 cat.mp4"

工具调用：

{
  "prompt": "一只可爱的橘猫在阳光洒满的木地板上缓慢行走，镜头跟随，温暖色调",
  "output_path": "cat.mp4"
}

示例 2：生成横屏视频

"生成一个横屏视频：科幻城市夜景，霓虹灯闪烁，赛博朋克风格，保存为 city.mp4"

工具调用：

{
  "prompt": "科幻城市夜景，霓虹灯闪烁，飞行汽车穿梭其间，赛博朋克风格，镜头缓慢上升",
  "output_path": "city.mp4",
  "orientation": "landscape"
}

示例 3：使用 sora-2-pro 生成高质量视频

"使用专业模型生成电影级森林晨雾场景，保存为 forest.mp4"

工具调用：

{
  "prompt": "电影级别的森林晨雾场景，阳光穿透树叶，细腻光影变化，鸟鸣回响",
  "output_path": "forest.mp4",
  "model": "sora-2-pro",
  "orientation": "landscape"
}

返回值

成功时：

{
  "status": "ok",
  "output_path": "/absolute/path/to/video.mp4",
  "file_size_bytes": 7506042,
  "prompt": "一只可爱的橘猫...",
  "orientation": "portrait",
  "model": "sora-2",
  "task_id": "task_01k7rdk408fsfvgqq8whb7pjnq",
  "generation_id": "gen_01k6fmwxqjfej860t5cszqmzvk",
  "video_url": "https://...",
  "width": 352,
  "height": 640
}

失败时：

{
  "status": "error",
  "message": "错误描述信息"
}

提示词技巧

✅ 好的提示词（具体、详细）

• "一只橘猫在木地板上缓慢行走，阳光从窗户洒进来，温暖的色调，镜头平稳跟随"
• "科幻城市夜景，高楼林立，霓虹灯闪烁，飞行汽车穿梭，赛博朋克风格，镜头从低处缓慢上升"
• "海浪轻柔拍打沙滩，夕阳西下，金色光线洒在水面，平静祥和，远景镜头"
• "一杯咖啡冒着热气，特写镜头，背景虚化，温馨的咖啡馆环境，暖色调"

❌ 不好的提示词（模糊、笼统）

• "一只猫"
• "城市"
• "海边"
• "咖啡"

高级技巧

1. 包含关键元素：

   • 主体：描述主要对象（人、动物、物体）
   • 动作：描述运动或变化
   • 环境：描述场景和背景
   • 光线：描述光线效果（阳光、霓虹灯、柔光等）
   • 氛围：描述整体感觉（温暖、科幻、平静等）
   • 镜头：描述镜头运动（跟随、上升、特写等）

2. 使用具体形容词：

   • 温暖的、柔和的、明亮的、阴暗的
   • 快速的、缓慢的、平稳的、急促的

3. 指定艺术风格：

   • 赛博朋克、水彩画、电影感、复古、现代简约

工作原理

Sora MCP 使用异步任务模式生成视频：

1. 提交任务 → 2. 轮询状态 → 3. 下载视频

详细流程：

1. 提交任务：

   • 发送提示词和参数到 api.tu-zi.com
   • 服务器返回 task_id

2. 轮询状态：

   • 每 10 秒检查一次任务状态
   • 最多轮询 60 次（总计 10 分钟）
   • 状态流转：queued → in_progress → completed

3. 下载视频：

   • 任务完成后获取 video_url
   • 自动下载并保存到指定路径

⏱️ 预计时间：2-10 分钟（取决于提示词复杂度和服务器负载）

常见问题

Q1: API 密钥设置后仍然报错？

解决方案：

1. 检查 .env 文件是否在项目根目录
2. 确认 API 密钥没有多余的空格或引号
3. 重启 MCP 服务器或 Cursor/Claude Desktop

Q2: 视频生成时间过长？

原因：

• Sora 视频生成通常需要 2-10 分钟
• 这是正常的，取决于提示词复杂度

解决方案：

• 耐心等待
• 检查任务状态（可能已在后台完成）

Q3: 任务失败怎么办？

可能原因：

1. API 密钥无效或过期
2. 提示词包含不适当内容
3. 服务器临时故障

解决方案：

1. 确认 API 密钥有效
2. 修改提示词内容
3. 稍后重试

Q4: 支持什么视频格式？

当前支持：

• 格式：MP4
• 竖屏：352 x 640（9:16）
• 横屏：640 x 352（16:9）
• 时长：约 15 秒

技术栈

• FastMCP: MCP 服务器框架
• httpx: 异步 HTTP 客户端
• asyncio: 异步任务处理
• Pydantic: 参数验证
• python-dotenv: 环境变量管理

相关资源

• api.tu-zi.com - Sora API 服务商
• Model Context Protocol - MCP 官方规范
• FastMCP - FastMCP 框架文档
• Cursor - AI 代码编辑器
• Claude Desktop - Anthropic 桌面应用

开发指南

本地测试

# 激活虚拟环境
source .venv/bin/activate  # macOS/Linux
# 或
.venv\Scripts\activate     # Windows

# 运行测试脚本
python -c "
import asyncio
from server import generate_video

async def test():
    result = await generate_video(
        prompt='一只可爱的猫在阳光下行走',
        output_path='test.mp4'
    )
    print(result)

asyncio.run(test())
"

项目结构

sora-mcp/
├── server.py          # MCP 服务器主逻辑
│   ├── generate_video()      # 视频生成工具函数
│   ├── _get_sora_api_key()   # API 密钥获取
│   └── main()                # 服务器启动入口
├── pyproject.toml     # 项目配置文件
├── .env               # 环境变量（不提交到 Git）
├── .env.example       # 环境变量模板
└── README.md          # 项目文档

许可证

本项目采用 MIT 许可证。详见 文件。

贡献

欢迎提交 Issue 和 Pull Request！

贡献指南：

1. Fork 本仓库
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

问题反馈

如果你遇到任何问题或有功能建议，请：

1. 查看 常见问题 部分
2. 搜索 已有 Issues
3. 如果问题未解决，创建新 Issue

⭐ 如果这个项目对你有帮助，请给个 Star！