LittleOrange Video MCP 是一款基于 Model Context Protocol (MCP) 开源标准的服务端工具，专为 AI 应用打造，提供统一、标准化的视频生成 API 调用能力。服务基于官方视频生成 API 文档封装，支持主流 AI 视频模型，内置智能轮询、分层工具能力，完美适配各类 AI 客户端与 Agent 场景。

协议标准：Model Context Protocol (MCP)

接口来源：视频生成大模型 API 官方文档

---

✨ 功能特性

• 多模型全覆盖：集成 Sora2、Veo3.1、Vidu Q3、Dreamina Seedance 2.0 等主流视频生成大模型

• 智能异步轮询：自动轮询异步任务，无需手动查询，直接返回最终视频链接与完整任务状态

• 三层工具架构：底层API映射、自动轮询工具、高层Agent工具，适配开发、自动化、AI代理全场景

• 完整素材管理：支持AIGC素材/素材组、真人认证素材的增删改查，适配商用素材流程

• 通用透传能力：内置原始请求透传工具，支持任意接口调试与新接口快速适配

• 结构化错误返回：标准化JSON错误信息，包含错误类型、描述、详情，便于排查问题

• 隔离式调试日志：日志写入本地文件，不污染MCP标准stdio通信协议

---

📌 覆盖范围

当前 v0.0.2 版本内置全套工具能力，覆盖视频生成、任务查询、素材管理全流程：

• ✅ 36 个基础文档接口工具

• ✅ 11 个「创建并自动等待」轮询工具

• ✅ 6 个高层 Agent 智能工具

• ✅ 1 个通用 API 透传调试工具

支持模型与功能明细

模型/类别	核心支持功能
基础示例接口	创建视频任务、查询任务状态
Sora2	文生视频、图生视频、任务状态查询
Veo3.1	文生视频、图生视频、视频时长扩展、任务查询
Vidu Q3	文生视频、图生视频、首尾帧生成视频、主体/非主体参考生视频、生成物查询
Dreamina Seedance 2.0	AI视频生成、任务状态查询
Dreamina 素材库	素材/素材组CRUD、真人认证素材管理、认证H5、认证结果查询、资产删除

---

🚀 快速开始

1. 获取 API Key

使用前需前往 LittleOrange 平台 注册账号，获取专属 API Key（密钥需妥善保管，禁止前端暴露）。

2. 安装 uv 包管理器

项目基于 uv 快速部署，未安装则执行以下命令安装：

curl -LsSf https://astral.sh/uv/install.sh | sh

更多安装方式参考：uv 官方仓库

3. 配置 MCP 客户端

方式一：uvx 直接启动（推荐，无需源码）

PyPI 发布版本，一键拉起服务，适配所有 MCP 客户端：

{
  "mcpServers": {
    "littleorange-video": {
      "command": "uvx",
      "args": ["littleorange-video-mcp"],
      "env": {
        "LITTLEORANGE_API_KEY": "sk-你的key",
        "LITTLEORANGE_TIMEOUT": "120",
        "LITTLEORANGE_BASE_URL": "https://vg-api.aig-ai.com",
        "LITTLEORANGE_POLL_INTERVAL_SECONDS": "10",
        "LITTLEORANGE_MAX_POLL_ATTEMPTS": "60",
        "LITTLEORANGE_FIRST_POLL_DELAY_SECONDS": "5",
        "LITTLEORANGE_DEBUG": "0"
      }
    }
  }
}

方式二：GitHub 源码部署

指定版本源码安装，适合需要最新迭代功能的场景：

{
  "mcpServers": {
    "littleorange-video": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/littleorange-ai/littleorange-video-mcp.git@0.0.2",
        "littleorange-video-mcp"
      ],
      "env": {
        "LITTLEORANGE_API_KEY": "sk-你的key",
        "LITTLEORANGE_TIMEOUT": "120",
        "LITTLEORANGE_BASE_URL": "https://vg-api.aig-ai.com",
        "LITTLEORANGE_POLL_INTERVAL_SECONDS": "10",
        "LITTLEORANGE_MAX_POLL_ATTEMPTS": "60",
        "LITTLEORANGE_FIRST_POLL_DELAY_SECONDS": "5",
        "LITTLEORANGE_DEBUG": "0"
      }
    }
  }
}

客户端专属配置说明

• TRAE（Windows）：直接复制上述推荐配置粘贴即可生效

• Cursor：Preferences → Cursor Settings → MCP → Add new global MCP Server，粘贴配置保存

• Claude Desktop：替换官方 MCP 配置文件对应内容

---

⚙️ 配置说明

环境变量配置（核心）

环境变量名	参数描述	默认值	必填
LITTLEORANGE_API_KEY	平台接口密钥，身份认证核心参数	无	✅ 是
LITTLEORANGE_BASE_URL	API 接口基础请求地址	https://vg-api.aig-ai.com	❌ 否
LITTLEORANGE_TIMEOUT	HTTP 请求超时时间（单位：秒）	120	❌ 否
LITTLEORANGE_POLL_INTERVAL_SECONDS	任务轮询间隔（单位：秒）	5	❌ 否
LITTLEORANGE_MAX_POLL_ATTEMPTS	最大轮询重试次数	60	❌ 否
LITTLEORANGE_FIRST_POLL_DELAY_SECONDS	首次轮询延迟时间（单位：秒）	5	❌ 否
LITTLEORANGE_DEBUG	调试日志开关（1开启 / 0关闭）	0	❌ 否
LITTLEORANGE_LOG_FILE	调试日志本地存储路径	无	❌ 否

⚠️ 重要说明：轮询参数支持双层优先级，单次调用传入参数可覆盖全局环境变量配置，灵活适配不同任务场景。

轮询参数场景推荐

使用场景	轮询间隔(秒)	最大轮询次数	首次延迟(秒)
快速调试	3	20	1
常规视频生成	5	60	2
长时长视频任务	10	120	3

本地开发安装

适合二次开发、本地调试场景：

# 进入项目目录
cd /path/to/littleorange-video-mcp

# 本地可编辑模式安装
python -m pip install -e .

无 pip 环境先安装依赖：

apt update && apt install -y python3-pip

本地开发 MCP 客户端配置：

{
  "mcpServers": {
    "littleorange-video": {
      "command": "python",
      "args": ["-m", "littleorange_video_mcp.server"],
      "env": {
        "LITTLEORANGE_API_KEY": "sk-你的key",
        "LITTLEORANGE_TIMEOUT": "120",
        "LITTLEORANGE_BASE_URL": "https://vg-api.aig-ai.com",
        "LITTLEORANGE_POLL_INTERVAL_SECONDS": "10",
        "LITTLEORANGE_MAX_POLL_ATTEMPTS": "60",
        "LITTLEORANGE_FIRST_POLL_DELAY_SECONDS": "5"
      }
    }
  }
}

---

🛠️ 工具分类

所有工具分为四大类，从底层原生调用到高层智能封装，适配不同开发与自动化需求。

1. 底层 API 映射工具

完全对齐官方原生接口，适合精细化自定义开发，支持参数灵活覆写。

通用入参：base_url、api_key、headers、query_params、request_body

2. 自动轮询工具（_wait）

推荐优先使用，自动完成「创建任务 + 轮询等待 + 结果返回」全流程，直接输出视频链接与任务信息。

统一返回字段：video_urls、elapsed_seconds、last_state、last_status、last_error、完整查询结果

模型	可用轮询工具
Sora2	sora2_t2v_wait、sora2_i2v_wait
Veo3.1	veo31_t2v_wait、veo31_i2v_wait、veo31_extend_wait
Vidu Q3	vidu_t2v_wait、vidu_i2v_wait、vidu_start_end_wait、vidu_ref_subj_wait、vidu_ref_wait
Dreamina	dreamina_create_video_wait

3. 高层 Agent 友好工具

极简封装、语义化命名，适配 IDE Agent、MCP 智能代理自动调用，无需手动区分模型。

工具名称	功能描述
video_generate_wait	通用文生视频（智能适配最优模型）
image_to_video_wait	通用图生视频
video_extend_wait	视频时长扩展
video_query	批量查询视频任务状态
asset_upload	上传自定义素材
asset_list	获取个人素材列表

4. 透传工具

通用调试工具 littleorange_raw_request，适配所有未封装接口、临时调试场景。

适用场景：新接口快速适配、请求头/参数调试、自定义原生请求、官方接口更新兼容

支持入参：base_url、query_params、headers、任意格式 request_body

---

🐛 错误处理与调试

标准化错误返回格式

所有异常统一返回结构化 JSON 数据，便于精准排查问题：

{
  "status": "error",
  "error_type": "http_error",
  "message": "HTTP 400",
  "details": {
    "method": "POST",
    "url": "https://vg-api.aig-ai.com/v1/viduq3-turbo",
    "params": {},
    "status_code": 400,
    "response_excerpt": "..."
  }
}

常见错误类型

• validation_error：参数校验失败

• request_error：请求参数异常

• http_error：接口HTTP状态码异常

• network_error：网络连接失败

• polling_timeout：轮询超时，任务未完成

• unknown_error：未知异常

调试日志配置

日志独立写入文件，不干扰 MCP 标准通信，开启方式：

LITTLEORANGE_DEBUG=1
LITTLEORANGE_LOG_FILE=/path/to/littleorange-debug.log

日志包含内容：请求方式、脱敏URL、查询参数、轮询次数、任务状态、耗时信息

---

❓ 常见问题 FAQ

Q1：任务完成后没有返回 video_urls？

可能原因：任务未真正完成、接口返回结构无视频地址、仅返回中间状态数据

解决方案：增大最大轮询次数、调整轮询间隔、查看 last_status 与任务最终返回数据

Q2：频繁出现轮询超时 timeout？

原因：视频生成任务耗时超出预设轮询上限

解决方案：调大 LITTLEORANGE_MAX_POLL_ATTEMPTS、适当增加轮询间隔，长任务建议设置为120次

Q3：提示缺少 API Key？

解决方案：配置全局环境变量 LITTLEORANGE_API_KEY，或单次调用单独传入密钥参数

Q4：TRAE 客户端看不到部分工具？

解决方案：重启 MCP 服务、更新至最新版本、检查配置文件是否生效、确认工具名长度合规

Q5：如何切换自定义 API 接口地址？

支持两种方式：全局修改 LITTLEORANGE_BASE_URL环境变量、单次调用传入 base_url 覆写

Q6：什么场景使用 raw_request 透传工具？

适用于：官方新增未封装接口、接口参数调试、自定义请求头、排查底层接口异常

---

💻 开发与测试

安装开发依赖

python -m pip install -e '.[dev]'

运行单元测试

# pytest 测试
pytest

# 原生 unittest 测试
python3 -m unittest discover -s tests -v

文档与接口更新

项目接口目录由 Apifox OpenAPI 文档自动生成，文件路径：littleorange_video_mcp/api_catalog.json

官方接口更新后，需重新生成接口目录并更新工具映射，过渡期可使用 littleorange_raw_request 临时适配新接口。

---

📝 版本历史

版本号	发布日期	核心更新内容
v0.0.2	2026-06-03	新增可自定义轮询参数、高层Agent工具、结构化错误返回、文件调试日志；优化TRAE/uvx部署配置
v0.0.1	2026-06-02	项目首次正式发布，完成基础视频模型接口封装与MCP服务搭建

详细版本迭代记录：GitHub Releases