Skip to main content
Glama
Hylouis233

minimax-mcode-byok

by Hylouis233
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

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: vimax-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 代替查询。

ParametersJSON Schema
NameRequiredDescriptionDefault
task_idYessubmit_video_generation 返回的 task_id（7 天内可查）。
output_file_pathYes成功后视频保存路径，如 "videos/result.mp4"。轮询时保持同一路径，仅 succeeded 时写入。签名 URL 约 9 小时有效，成功后立即落盘。

TDQS

A4.6/5.0
Behavior5/5

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

No annotations are provided, so the description carries the full burden. It discloses read-only/no-cost behavior, the side effect of downloading on status=succeeded, signed URL validity of ~9 hours, and the instruction to write immediately. This is strong behavioral disclosure for a tool with no annotations.

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

Conciseness5/5

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

The description is compact with no filler. It front-loads the core purpose and read-only nature, then states the success behaviorasio and usage warning in separated, scannable sentences.

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

Completeness4/5

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

With only two parameters and no output schema, the description covers the critical workflow: query, success download, path stability, URL expiry, and separation from submit. The only minor gap is that non-success return behavior is not explicitly described, though the tool name and first phrase imply a status response.

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?

Schema description coverage is 100% and both parameters already have rich descriptions: task_id provenance and 7-day validity, output_file_path semantics including same-path polling and write-on-succeeded. The description adds little beyond what the schema already provides, so baseline 3 is appropriate.

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 explicitly states the verb and resource: '查询一次视频任务状态' (query a video task status), and notes read-only/non-billing. It also differentiates from the sibling submit_video_generation by warning not to use repeated submit calls. Clear and unambiguous.

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

Usage Guidelines5/5

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

Gives explicit preconditions: only call after obtaining task_id, and do not substitute repeated submit calls for querying. The polling behavior and same-path requirement are also clearly stated. This leaves little ambiguity about when and how to use the tool.

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

submit_video_generationA

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

ParametersJSON Schema
NameRequiredDescriptionDefault
modelYes视频模型。MiniMax-H3：质量档，768P/2K，4-15 秒；MiniMax-H3-Max：极速档，480P/768P，5-15 秒。
ratioNo画面比例。纯文生视频必为具体比例（默认 16:9）；首尾帧模式恒为 adaptive；参考模式默认 adaptive。
promptYes必填提示词（≤7000 字符）。H3 原生出音：对白、环境音、音效都写在这里。
durationYes时长（秒）。
resolutionNo分辨率，缺省时 H3 默认 2K、H3-Max 默认 768P。
aigc_watermarkNo是否加 AIGC 水印。
reference_typeNoinput_image_path 的角色，默认 first_frame。
input_image_pathNo首帧/尾帧图片：公网 URL、mm_file:// 或本地文件路径。不能与参考素材(reference_*)混用。
last_frame_image_pathNo尾帧图片（首+尾帧模式）。需要同时提供 input_image_path 作为首帧。
reference_audio_pathsNo可选参考音频 1-3 个（须搭配参考图/视频），单段 2-15s。
reference_image_pathsNo多模态参考图 1-9 张（r2v 模式），与首尾帧互斥。
reference_video_pathsNo参考视频 1-3 个，单段 2-15s、总时长 ≤15s。仅支持 H3。

TDQS

A4.1/5.0
Behavior4/5

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

With no annotations present, the description carries the full behavioral burden and does a solid job: it discloses the async nature (returns task_id immediately), the exact endpoint being called, the billing model distinction, and the no-auto-retry policy. It doesn't mention rate limits, partial-failure semantics, or response shape, but for a latency-sensitive submission tool the key behaviors are covered.

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?

Three sentences with no filler, logically ordered: core purpose first, then billing/endpoint context, then the retry instruction. Efficient for a tool with 12 parameters. Slight opportunity would be to integrate the workflow link (submit→query) into that space, but nothing is wasted.

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

Completeness4/5

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

Given 12 parameters, no output schema, and no annotations, the description covers the essentials: async contract, billing, endpoint, error-handling expectation. The schema handles param semantics thoroughly. The main gap is the lack of an explicit pointer to the query_video_generation sibling for the retrieve-results step of the workflow, which would complete the agent's mental model for this async operation.

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?

Schema description coverage is 100% and the schema itself is exceptionally rich, documenting per-parameter constraints, modes, and mutual exclusions (e.g., '不能与参考素材混用' for input_image_path, defaults per model, maxItem counts). The description adds model-level context (BYOK billing, endpoint) but no per-parameter meaning beyond the schema. Baseline 3 is appropriate given full schema coverage.

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?

The description states a specific verb+resource: 'submit an async video generation task, immediately return task_id'. It clearly differentiates from the sole sibling query_video_generation by framing the submission action vs. (implicitly) querying. An agent can immediately grasp what this tool does and how it relates to the sibling.

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 BYOK billing context ('直接官方 POST /v2/video_generation，按 API Key 计费，不走订阅额度') gives clear financial/usage context that helps an agent decide when this tool is appropriate. The explicit '提交失败不要自动重试' instruction adds operational guidance. However, it never explicitly names the query_video_generation sibling as the follow-up step for retrieving results, relying instead on inference from the async + task_id phrasing.

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

Tool Schema Changelog

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

  1. 2 tool updatesv1.1.0
    • First observedquery_video_generation
    • First observedsubmit_video_generation
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

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

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers