# Sora MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)

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

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

## 功能特性

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

## 文件结构

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

## 快速开始

### 1. 环境准备

**系统要求：**
- Python >= 3.11
- [uv](https://github.com/astral-sh/uv) 包管理器（推荐）

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

### 2. 安装依赖

```bash
# 进入项目目录
cd sora-mcp

# 创建虚拟环境
uv venv

# 安装依赖
uv pip install -e .
```

### 3. 配置 API 密钥

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

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

### 4. 启动 MCP 服务器

```bash
# 直接运行
python server.py

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

### 5. 配置 Cursor 或 Claude Desktop

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

**配置文件位置：**
- **macOS/Linux:** `~/.cursor/mcp.json`
- **Windows:** `%USERPROFILE%\.cursor\mcp.json`

**配置内容：**
```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 连接状态

**如何获取绝对路径：**
```bash
# 进入项目目录
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`

**配置内容：**
```json
{
  "mcpServers": {
    "sora-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/sora-mcp",
        "run",
        "server.py"
      ]
    }
  }
}
```

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

## 使用说明

### 🎬 工具：`generate_video`

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

#### 参数说明

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `prompt` | string | ✅ | - | 视频生成提示词，支持中英文 |
| `output_path` | string | ✅ | - | 输出文件路径（.mp4） |
| `orientation` | string | ❌ | portrait | 视频方向：portrait（竖屏）或 landscape（横屏） |
| `model` | string | ❌ | sora-2 | Sora 模型：sora-2（标准质量）、sora-2-pro（专业高质量） |

#### 使用示例

**示例 1：生成竖屏视频**
```
"生成一个视频：一只可爱的橘猫在阳光下行走，保存为 cat.mp4"
```

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

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

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

**示例 3：使用 sora-2-pro 生成高质量视频**
```
"使用专业模型生成电影级森林晨雾场景，保存为 forest.mp4"
```

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

#### 返回值

**成功时：**
```json
{
  "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
}
```

**失败时：**
```json
{
  "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](https://api.tu-zi.com) - Sora API 服务商
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP 官方规范
- [FastMCP](https://github.com/jlowin/fastmcp) - FastMCP 框架文档
- [Cursor](https://cursor.sh/) - AI 代码编辑器
- [Claude Desktop](https://claude.ai/desktop) - Anthropic 桌面应用

## 开发指南

### 本地测试

```bash
# 激活虚拟环境
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 许可证。详见 [LICENSE](LICENSE) 文件。

## 贡献

欢迎提交 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](https://github.com/airsulG/sora-mcp/issues)
3. 如果问题未解决，[创建新 Issue](https://github.com/airsulG/sora-mcp/issues/new)

---

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