Littleorange Video Mcp

LittleOrange Video MCP 官方文档

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通信协议

---

📌 覆盖范围

内置全套工具能力，覆盖视频生成、任务查询、素材管理全流程：

• ✅ 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/[email protected]",
        "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	プラットフォーム API キー。認証の中核となるパラメーター	なし	✅ はい
LITTLEORANGE_BASE_URL	API の基本リクエスト URL	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	デバッグログのローカル保存先	なし	❌ いいえ
LITTLEORANGE_CATALOG_AUTO_UPDATE	API カタログの自動更新のオン／オフ（0でオフ／1でオン）	1	❌ いいえ
LITTLEORANGE_CATALOG_REFRESH_SECONDS	API カタログのキャッシュ更新間隔（秒）。0に設定すると、毎回公式ドキュメントを確認します	3600	❌ いいえ
LITTLEORANGE_CATALOG_FORCE_REFRESH	API カタログを強制更新（1=毎回Apifoxから取得）	0	❌ いいえ
LITTLEORANGE_CATALOG_LOG_FILE	カタログ更新ログのローカル保存先	なし	❌ いいえ
LITTLEORANGE_CATALOG_CACHE_FILE	API カタログのキャッシュファイルパス	システムキャッシュディレクトリ	❌ いいえ

⚠️ 重要な説明：ポーリングパラメーターは二段階の優先順位に対応しています。個別の呼び出しで指定したパラメーターは、グローバルな環境変数の設定を上書きでき、タスクごとのニーズに柔軟に対応します。

ポーリングパラメーターの推奨設定

使用シナリオ	ポーリング間隔（秒）	ポーリング最大回数	初回待機時間（秒）
高速デバッグ	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"
      }
    }
  }
}

---

🛠️ ツールの分類

すべてのツールは4つのカテゴリに分類されています。低レベルのネイティブ呼び出しから高レベルのインテリジェントなラッパーまで、さまざまな開発や自動化のニーズに対応します。

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. 高レベルのエージェント向けツール

シンプルなラッパーと意味の分かりやすい命名を採用しており、IDE エージェントや 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 透传工具？

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

Q7：如何立即获取最新的 Apifox 接口文档？

快速方法：

1. 临时设置环境变量：LITTLEORANGE_CATALOG_FORCE_REFRESH=1
2. 重启 MCP 服务
3. 获取更新后记得改回 0 避免频繁请求

Q8：目录刷新机制的工作原理是什么？

1. 默认每 1 小时检查一次 Apifox 文档更新
2. 如果缓存过期，从 Apifox 下载最新文档
3. 如果网络不可用，使用最近一次缓存
4. 没有缓存时使用包内置的兜底目录

Q9：如何查看目录刷新日志？

设置环境变量：

• LITTLEORANGE_DEBUG=1
• LITTLEORANGE_CATALOG_LOG_FILE=/path/to/catalog.log

日志会记录：刷新时间、来源、接口数量、SHA256 校验等信息。

---

💻 开发与测试

安装开发依赖

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

运行单元测试

# pytest 测试
pytest

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

文档与接口更新

MCP 服务启动时会自动读取 Apifox 官方 OpenAPI 文档并生成运行时接口目录，缓存文件默认位于系统缓存目录。官方接口更新后，用户重启 MCP 服务即可自动刷新接口目录和工具映射，不需要等待新的 MCP/PyPI 版本发布。

内置兜底目录文件路径：littleorange_video_mcp/api_catalog.json。当网络不可用或官方文档临时不可访问时，会自动使用最近一次缓存；如果没有缓存，则使用包内置目录。

可配置项：

• LITTLEORANGE_CATALOG_AUTO_UPDATE=1：默认开启自动更新；设为 0 可关闭。
• LITTLEORANGE_CATALOG_REFRESH_SECONDS=3600：缓存刷新间隔，默认 1 小时；设为 0 表示每次启动都检查官方文档。
• LITTLEORANGE_CATALOG_FORCE_REFRESH=0：强制刷新接口目录，设为 1 表示每次都从 Apifox 拉取最新文档。
• LITTLEORANGE_CATALOG_LOG_FILE=/path/to/catalog.log：目录刷新日志文件路径（可选）。
• LITTLEORANGE_CATALOG_CACHE_FILE=/path/to/api_catalog.json：自定义缓存文件路径（可选）。

快速获取最新接口方法：

1. 设置环境变量：LITTLEORANGE_CATALOG_FORCE_REFRESH=1
2. 重启 MCP 服务
3. 获取更新后记得改回 0 避免频繁请求

过渡期或新接口尚未形成稳定封装命名时，可使用 littleorange_raw_request 临时适配新接口。

---

📝 版本历史

版本号	发布日期	核心更新内容
v0.0.4	2026-06-04	优化接口目录自动刷新机制：缩短默认刷新间隔为1小时，新增强制刷新与日志功能
v0.0.3	2026-06-04	新增启动时自动刷新 Apifox 官方文档接口目录与工具映射；清理发布包冗余文档
v0.0.2	2026-06-03	新增可自定义轮询参数、高层Agent工具、结构化错误返回、文件调试日志；优化TRAE/uvx部署配置
v0.0.1	2026-06-02	项目首次正式发布，完成基础视频模型接口封装与MCP服务搭建

详细版本迭代记录：GitHub Releases