Skip to main content
Glama
airsulG

sora-mcp

by airsulG
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

Sora MCP Server

License: MIT Python 3.11+

一个使用 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 密钥，完善的错误处理

Related MCP server: Grok Imagine Video MCP Server

文件结构

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

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

参数说明

参数

类型

必填

默认值

说明

prompt

string

✅

-

视频生成提示词，支持中英文

output_path

string

✅

-

输出文件路径（.mp4）

orientation

string

❌

portrait

视频方向：portrait（竖屏）或 landscape（横屏）

model

string

❌

sora-2

Sora 模型：sora-2（标准质量）、sora-2-pro（专业高质量）

使用示例

示例 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: 环境变量管理

相关资源

开发指南

本地测试

# 激活虚拟环境
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 文件。

贡献

欢迎提交 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！

Available Tools

1 tool
generate_videoA

使用 Sora 模型生成视频并保存到指定路径（异步任务模式）。

通过 api.tu-zi.com 官方格式接口调用 Sora 视频生成模型。 采用任务提交 → 轮询状态 → 下载视频的异步流程。

⚠️ 重要提示：

  • 视频生成时间较长，通常需要 2-10 分钟，请耐心等待

  • 建议提示词详细且具体，包含场景、动作、风格等元素

  • 支持中文和英文提示词

  • 采用异步轮询机制，每 10 秒检查一次任务状态

Args: prompt: 视频生成提示词，描述越详细越好 output_path: 输出视频文件路径（.mp4） orientation: 视频方向，'portrait'（竖屏）或 'landscape'（横屏） model: Sora 模型名称，默认 'sora-2'（最新版本） ctx: MCP 上下文，用于日志记录

Returns: 包含生成结果的字典： - status: "ok" 或 "error" - output_path: 保存的视频文件路径（绝对路径） - file_size_bytes: 文件大小（字节） - prompt: 使用的提示词 - orientation: 视频方向 - model: 使用的模型名称 - task_id: 任务 ID - video_url: 视频下载 URL - size: 视频尺寸规格（如 "small"） - seconds: 视频时长（秒） - created_at: 创建时间戳 - message: 错误信息（失败时）

Examples: >>> # 生成竖屏视频（使用默认 sora-2 模型） >>> result = await generate_video( ... prompt="一只可爱的橘猫在阳光下缓慢行走", ... output_path="videos/cat_walking.mp4" ... )

>>> # 生成横屏视频（使用默认 sora-2）
>>> result = await generate_video(
...     prompt="科幻城市夜景，霓虹灯闪烁，赛博朋克风格",
...     output_path="videos/cyberpunk_city.mp4",
...     orientation="landscape"
... )

>>> # 使用 sora-2-pro 模型生成高质量视频
>>> result = await generate_video(
...     prompt="电影级别的森林晨雾场景，阳光穿透树叶，细腻光影变化",
...     output_path="videos/forest_cinematic.mp4",
...     model="sora-2-pro",
...     orientation="landscape"
... )
ParametersJSON Schema
NameRequiredDescriptionDefault
modelNo【可选】Sora 模型名称，默认 'sora-2'（标准版本）。可选值：• 'sora-2'：标准版本，平衡质量与速度，推荐日常使用；• 'sora-2-pro'：专业版本，质量最高，细节最丰富，但生成时间较长。建议：大多数情况使用默认的 'sora-2'；追求极致质量和细节选择 'sora-2-pro'。示例：model='sora-2-pro' 用于高质量商业视频、电影级别制作sora-2
promptYes【必填】视频生成提示词。使用自然语言详细描述您想要生成的视频内容。描述越详细越好，建议包含：场景、动作、光线、氛围、镜头运动等元素。支持中文和英文提示词。示例：'一只可爱的橘猫在阳光洒满的木地板上缓慢行走，镜头跟随，温暖色调'、'科幻城市夜景，霓虹灯闪烁，飞行汽车穿梭其间，赛博朋克风格，镜头缓慢上升'、'海浪拍打着沙滩，夕阳西下，金色的光线洒在水面上，平静祥和的氛围'、'一杯咖啡冒着热气，特写镜头，背景虚化，温馨的咖啡馆环境'。
orientationNo【可选】视频方向，默认 'portrait'（竖屏）。可选值：'portrait'（竖屏，9:16）、'landscape'（横屏，16:9）。示例：orientation='landscape' 适合宽屏内容、横版视频portrait
output_pathYes【必填】输出视频文件保存路径。支持绝对路径和相对路径。文件扩展名应为 .mp4。目录会自动创建，无需手动创建父目录。示例：'/Users/username/videos/output.mp4'、'output/video.mp4'、'~/Desktop/video.mp4'

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description clearly discloses the async behavior, expected duration (2-10 minutes), polling interval (10 seconds), and the fact that the directory is auto-created. Since no annotations are provided, the description carries the behavioral disclosure burden and does so well.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with headers, warnings, Args, Returns, and Examples. It is somewhat long but each section earns its place, and the critical warning is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is complete for an async video-generation tool: it covers the workflow, time expectations, parameter semantics, return values, and examples. With no annotations or sibling tools, it fully compensates for missing context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already has 100% coverage with detailed descriptions. The description's Args section is largely redundant with the schema. However, it adds context about prompt detail level and async behavior that complements the schema. Baseline 3 is appropriate since schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description states the verb (generate), resource (video using Sora model), and delivery mechanism (save to specified path via async task). It clearly distinguishes the tool's purpose and is not tautological.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains when and how to use the tool, including the async flow, polling mechanism, timing expectations, and prompt-quality guidance. It does not explicitly describe when not to use it or name alternatives (there are no sibling tools), but it provides sufficient usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0
Disambiguation5/5

Only one tool exists, so there is no possibility of overlap or mis-selection. The single tool's purpose is clearly defined a video generation.

Naming Consistency5/5

The sole tool uses a clear snake_case verb_noun convention: generate_video. With no other tools there are no conflicting naming patterns to confuse an agent.

Tool Count3/5

A single tool makes the server feel minimal and borderline thin for a video-generation service. However, the tool does encapsulate the full submit/poll/download workflow, so the count is not clearly inadequate.

Completeness4/5

The core video generation lifecycle is covered end-to-end within generate_video, including async polling and file saving. Minor gaps exist, such as no separate task-status or cancellation endpoint, but agents can still accomplish the primary use case without dead ends.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/airsulG/sora-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server