Skip to main content
Glama

minimax-mcode-byok

MiniMax(海螺 H3)视频生成 BYOK MCP Server,为 mcode(Minimax Code CLI)设计。

把 mcode 内置 Matrix 的 submit_video_generation / query_video_generation 两个工具移植到官方开放平台 V2 API,用你自己的 API Key 鉴权(BYOK,Bring Your Own Key)——视频生成按开放平台计费(积分/按量),不占用 mcode 订阅套餐(Token Plan)的视频条数和周限额。

非官方社区工具,与 MiniMax 公司无隶属关系。接口以开放平台文档为准。

适用场景

  • mcode 已登录(OAuth 订阅)状态下,内置 Matrix 视频工具与本项目并存不冲突(MCP 工具名自动带 server 前缀),可按需选择走订阅额度还是走 API Key

  • 订阅的每日视频条数用完,还想继续生成

  • 想把视频生成费用与订阅额度分开结算

Related MCP server: Seedance MCP

工作方式

mcode (TUI/ACP) ──MCP stdio──> mcp-server.mjs ──HTTPS──> 官方开放平台 API
                                                    POST /v2/video_generation        (提交,得 task_id)
                                                    GET  /v2/query/video_generation/ (轮询,取结果 URL)

暴露两个工具(入参与内置 Matrix 版对齐):

工具

作用

submit_video_generation

提交异步视频任务,立即返回 task_id

query_video_generation

查询状态;succeeded 时自动把 mp4 下载到你指定的路径(签名 URL 约 9 小时有效,落盘不担心过期)

请求标识:以 mcode 客户端身份发出

本 server 的所有 API 请求默认携带 User-Agent: MiniMaxCode——与 mcode 调用开放平台 API 时使用的客户端标识一致。因此即使走的是 API Key(BYOK)格式,请求在服务端遥测/风控视角也呈现为 mcode 客户端发出,与 mcode 自身的 BYOK 模式行为对齐。

  • 鉴权与计费不受影响:仍用你自己的 API Key,费用归属 Key 所属账户(按量/积分),不动订阅额度

  • 如需自定义,用环境变量 MINIMAX_VIDEO_UA 覆盖(设为 "" 之外的任意值)

安装

前置:已安装 mcode(Minimax Code CLI);Node.js 18+(mcode 自带 runtime 也可)。

  1. 获取 API Key:platform.minimax.cn(国际站 platform.minimaxi.com)→ 账户管理 → 接口密钥

  2. 克隆本仓库(路径任意,记住 mcp-server.mjs 的完整路径):

    git clone https://github.com/Hylouis233/minimax-mcode-byok.git
  3. 注册到 mcode:编辑 mcode 用户级 MCP 配置 ~/.minimax/mcp.json(Windows 为 C:\Users\<你>\.minimax\mcp.json;文件已存在则把条目合并进已有的 mcpServers):

    {
      "mcpServers": {
        "minimax-mcode-byok": {
          "command": "node",
          "args": ["C:\\path\\to\\minimax-mcode-byok\\mcp-server.mjs"],
          "env": {
            "MINIMAX_API_KEY": "你的开放平台APIKey",
            "MINIMAX_VIDEO_API_BASE": "https://api.minimax.cn"
          },
          "enabled": true,
          "description": "MiniMax 视频生成 BYOK(官方 V2 API,按 API Key 计费)"
        }
      }
    }
    • node 不在 PATH 时,可改用 mcode 自带 Node 的完整路径,如 %USERPROFILE%\.minimax-code\runtime\node-v22.19.0-win-x64\node.exe(版本号以本机为准)

    • 国际站账号把 MINIMAX_VIDEO_API_BASE 改为 https://api.minimaxi.com

  4. 重启 mcode,在 TUI 里直接说人话即可,例如:

    用 minimax-mcode-byok 生成一个 6 秒 2K 视频:夜晚的赛博朋克街道,霓虹雨幕,说一句"欢迎回家"

    模型、时长(H3 4–15 秒、H3-Max 5–15 秒)、分辨率(768P/2K)、比例它会先问你;任务完成后 mp4 自动保存到工作区。

支持的输入

  • 模型:MiniMax-H3(质量档,768P/2K)、MiniMax-H3-Max(极速档,480P/768P)

  • 模式:纯文生视频 / 首帧·尾帧·首+尾帧 / 多模态参考(参考图 ≤9、参考视频 ≤3、参考音频 ≤3,总数 ≤12)

  • 媒体:公网 HTTP(S) URL 与 mm_file:// 直接透传;本地文件自动转 base64(受官方 64MB 请求体上限,大文件请用公网 URL)

  • H3 原生同步出音:对白、环境音、音效写进 prompt 即可

限制

  • MiniMax-Hailuo-2.3 走旧版 V1 接口,本工具不包装(调用会返回明确提示)——H2.3 请继续用 mcode 内置 Matrix 工具

  • 任务查询窗口 7 天

  • 计费按 API Key 走开放平台(参考价:国内站 2K ≈ ¥0.8/秒、768P ≈ ¥0.5/秒,以价格页为准)

排障

现象

处理

1004 login fail / 401

API Key 错误,或 Key 与 MINIMAX_VIDEO_API_BASE 站点不匹配(cn 的 Key 别配 minimaxi.com)

工具没出现在 mcode

检查 mcp.json 是合法 JSON、args 路径正确、node 可用;重启 mcode

credits_exhausted / 402

开放平台余额不足,充值或换 Key

大视频文件报超过 64MB

改用公网 URL 引用

License

MIT

Available Tools

2 tools
query_video_generationA

查询一次视频任务状态(只读,不产生费用)。status=succeeded 时立即把视频下载到 output_file_path 并返回路径;签名 URL 约 9 小时有效。只在拿到 task_id 后调用,不要用重复 submit 代替查询。

Inputs: task_id (required), output_file_path (required).

submit_video_generationA

提交一个异步视频生成任务,立即返回 task_id。BYOK 版:直连官方 POST /v2/video_generation,按 API Key 计费(积分/余额),不走订阅额度。提交失败不要自动重试,如实报告错误。

Inputs: model (required), prompt (required), duration (required), ratio, +8 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools have clearly distinct roles: one submits an asynchronous generation job, the other queries its status and downloads the result. There is no overlap or ambiguity.

    Naming Consistency5/5

    Both tools follow the same verb_noun pattern: submit_video_generation and query_video_generation. The naming is consistent and predictable.

    Tool Count4/5

    With only two tools, the set is minimal but appropriate for the narrow async video-generation workflow. Each tool is essential, though slightly thin compared to typical servers.

    Completeness4/5

    The core lifecycle of submit, query, and download is covered. Missing cancel or listing operations, but for the stated BYOK video-generation purpose the essential surface is present.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers