Skip to main content
Glama
README.md
# H3 Cloud MCP

用本地 MCP 客户端调用 [AutoDL Art 的 MiniMax H3 托管工作流](https://www.autodl.art/large-model/comfyui/minimax_h3_lightx2v_no_pic):提交文生、首尾帧、图片或音频参考任务,查询状态并下载 MP4。视频由 AutoDL Art 托管生成,使用者无需为这条路线单独租 GPU 或下载模型权重。

**当前状态:**MCP 已按 AutoDL Art 的参数表接入目录中的 **18 个 H3 工作流**,覆盖文生、首尾帧、多图和多音频。文生视频链路真实跑通两次:两条 5 秒、480p 横屏样片分别实扣 **¥0.20**,产物均为 864×480、5.167 秒的 H.264/AAC MP4。其他工作流已做参数校验与本地模拟测试,尚未逐个付费出片。仓库不含样片、令牌或个人资料。此 MCP 在你的电脑上以 stdio 运行,并不是已经部署好的公共在线服务。

> [完整使用说明书](docs/user-guide.md):从注册/登录、实名认证、设置限额令牌,到安装、出片、核对账单和常见问题。首次使用请按说明书操作。

## 能做什么

| 已接通的托管工具 | 用途 |
| --- | --- |
| `h3_art_quote` | 按 2026-10-26 观察价格**本地估算**,不调用平台,不产生费用。 |
| `h3_art_generate` | 提交一条付费文生视频任务,返回 `task_id`。 |
| `h3_art_list_workflows` | 列出 18 个工作流的类别、分辨率、时长和素材要求。 |
| `h3_art_quote_workflow` | 按所选工作流估算价格,不产生费用。 |
| `h3_art_generate_workflow` | 按工作流 ID 提交文生、首尾帧、多图或多音频任务;素材使用 HTTPS URL。 |
| `h3_art_job_status` | 根据 `task_id` 查询排队、运行或完成状态。 |
| `h3_art_download_video` | 下载完成的 MP4 到本机 `outputs/`,或 `H3_OUTPUT_DIR` 指定的位置。 |

原有的 `h3_art_generate` 是已实测文生工作流 `minimax_h3_lightx2v_no_pic` 的快捷入口;新工具按各工作流要求选择分辨率、时长、必填图片与音频。**18 个工作流的价格已核对,但只有文生工作流真实出片验收**。图片和音频输入当前使用可访问的 HTTPS URL;本机文件上传尚未接入。[各类别及分辨率](docs/h3-price-matrix.md)、[调用示例](docs/user-guide.md)。

## 五步开始(macOS)

1. 在 [AutoDL Art](https://autodl.art/) 登录;若平台要求,先完成实名认证。在[令牌管理](https://autodl.art/large-model/tokens)创建 **ComfyUI** 分组令牌,设置你能接受的总额度与短有效期。创建后检查页面显示的实际额度。
2. 安装 Python 3.11+、[`uv`](https://docs.astral.sh/uv/);克隆仓库并安装依赖:

   ```sh
   git clone https://github.com/lst016/h3-cloud-mcp.git
   cd h3-cloud-mcp
   uv sync
   ```
3. 在你自己的交互式终端中,将令牌存入 macOS 钥匙串:

   ```sh
   security add-generic-password -U -a "$(id -un)" -s h3-cloud-mcp-autodl-art -w
   ```

   命令会提示输入令牌;不要把令牌写进命令参数、MCP 配置或 Git。其他操作系统可用自己的秘密管理器向 MCP 进程提供 `AUTODL_ART_TOKEN`。
4. 在仓库目录运行下列命令,把脚本的**绝对路径**注册到 Codex CLI;其他 MCP 客户端配置为同一个 stdio 命令。

   ```sh
   codex mcp add h3-art -- /absolute/path/h3-cloud-mcp/scripts/run-art-mcp-macos.sh
   ```

5. 打开**所选工作流**的价格页核对实时单价,再在 MCP 客户端调用 `h3_art_list_workflows` → `h3_art_quote_workflow` → `h3_art_generate_workflow` → `h3_art_job_status` → `h3_art_download_video`。只做已实测文生时,也可使用快捷工具:`h3_art_generate({"prompt":"一只透明玻璃鲸鱼在桌面上方缓慢游动,单镜头,无文字","duration":5,"resolution":"480p横"})`。

完整参数、Codex 配置、Windows/Linux 说明和出错处理见[使用说明书](docs/user-guide.md)。`scripts/run-art-mcp-macos.sh` 会启用付费提交,并在**每个 MCP 进程**中限制最多 1 条任务、按已观察高峰价估算最多 ¥0.25。这个本地估算不是平台账单上限;平台令牌额度要单独设置。提交超时后先查平台任务与账单,**不要盲目重复提交**。

## 成本:5 秒输出示例

| 路线与分辨率 | 单价 | 5 秒输出费用 | 证据 |
| --- | ---: | ---: | --- |
| AutoDL Art 托管工作流,480p 高峰 | ¥0.04/秒 | **¥0.20** | 两条真实样片分别实扣 ¥0.20 |
| AutoDL Art 托管工作流,480p 空闲 | ¥0.03/秒 | ¥0.15 | 页面报价,未在空闲时段实测 |
| AutoDL Art 托管工作流,768p 高峰/空闲 | ¥0.05/¥0.04 每秒 | ¥0.25/¥0.20 | 页面报价,未实测 |
| MiniMax 官方 H3-Lite API,480P | $0.025/秒 | 约 ¥0.84 | 官方目录价换算,未实测 |
| MiniMax 官方 H3 API,768P | $0.08/秒 | 约 ¥2.69 | 官方目录价换算,未实测 |

2026-10-26 汇率按 [100 美元 = ¥671.62](https://www.safe.gov.cn/AppStructured/hlw/RMBQuery.do)换算;[MiniMax 官方定价](https://platform.minimax.io/docs/pricing/overview)的输入视频和超额图片可能另收费。**不同型号与工作流的画质、排队和处理过程没有做同条件对照**。所有模型、分辨率、素材附加费和 AutoDL Art 18 个工作流的报价见[价格矩阵](docs/h3-price-matrix.md)。价格会变动,付费前以平台当前页面和账户预算为准。

## 文档与边界

- [使用说明书](docs/user-guide.md):账户准备、令牌、安装、完整调用流程、成本和故障处理。
- [价格矩阵](docs/h3-price-matrix.md):官方 H3 全型号与 AutoDL Art 18 个工作流。
- [验收记录](docs/validation.md):两条真实出片与费用证据。
- [私有 ComfyUI 备用路线](docs/private-comfyui.md):需自行租 GPU,当前只通过本地模拟测试,**未完成真实出片验收**。

公开仓库的 MIT 许可只覆盖本仓库代码。MiniMax H3 权重另受 [MiniMax H3 Community License](https://huggingface.co/MiniMaxAI/MiniMax-H3/blob/main/LICENSE) 约束;自行部署模型或向第三方提供服务前,应核对现行许可与使用地区。不要公开 API 令牌、签名下载地址或未经同意的素材。

TDQS

B3.1/5.0

Scored across 12 tools

Disambiguation3/5

The set contains two parallel stacks (h3_art_* for managed AutoDL Art and h3_* for the private ComfyUI tunnel), producing near-duplicate tools like h3_art_job_status/h3_job_status and h3_art_download_video/h3_download_video. Descriptions clarify the managed vs. private distinction, but an agent must read carefully to avoid picking the wrong backend.

Naming Consistency3/5

All names are snake_case with an h3_ prefix, but the naming mixes noun-first forms (h3_art_job_status, h3_job_status) with verb-first forms (h3_check_backend, h3_generate, h3_cancel_job). The two prefix families are predictable internally, yet the overall convention is not uniform.

Tool Count4/5

12 tools is well within a reasonable range for a video-generation server covering quote, generate, status, download, and cancel flows. There is some duplication from maintaining both managed and private backends, but each tool is plausibly needed.

Completeness4/5

Core lifecycle is covered: pricing quotes, workflow discovery, generation, job status, download, and cancellation, plus backend health checking. Minor gaps exist, such as no explicit cancellation for managed AutoDL Art jobs and no job-listing operation.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues