MiniMax MCP JS

文档

• 中文文档
• Python 版本 - MiniMax MCP 的官方 Python 实现

发布说明

2025 年 7 月 22 日

🔧 修复与改进

• TTS 工具修复：修复了 text_to_audio 工具中 languageBoost 和 subtitleEnable 的参数处理问题
• API 响应增强：TTS API 可同时返回音频文件和字幕文件，提供更完整的语音转文本体验

2025 年 7 月 7 日

🆕 新增内容

• 语音设计：新增 voice_design 工具，可根据描述性提示词创建自定义语音，并提供预览音频
• 视频增强：新增 MiniMax-Hailuo-02 模型，支持超清画质以及时长／分辨率控制

📈 工具增强

• voice_design - 根据文本描述生成个性化语音
• generate_video - 现已支持 MiniMax-Hailuo-02，可选 6 秒／10 秒时长和 768P／1080P 分辨率

功能

• 文本转语音（TTS）
• 图像生成
• 视频生成
• 语音克隆
• 语音设计
• 动态配置（支持环境变量和请求参数）
• 兼容 MCP 平台托管（ModelScope 及其他 MCP 平台）

安装

通过 Smithery 安装

通过 Smithery 自动为 Claude Desktop 安装 MiniMax MCP JS：

npx -y @smithery/cli install @MiniMax-AI/MiniMax-MCP-JS --client claude

手动安装

# Install with pnpm (recommended)
pnpm add minimax-mcp-js

快速开始

MiniMax MCP JS 实现了 Model Context Protocol（MCP） 规范，可作为服务与兼容 MCP 的客户端（例如 Claude AI）交互。

使用 MCP 客户端快速开始

1. 从 MiniMax 国际平台 获取 API 密钥。
2. 确保已安装 Node.js 和 npm
3. 重要：不同区域的 API HOST 和 KEY 不同，两者必须匹配，否则会收到 Invalid API key 错误。

区域	全球	中国大陆
MINIMAX_API_KEY	从 MiniMax Global 获取	从 MiniMax 获取
MINIMAX_API_HOST	​https://api.minimaxi.chat（注意多出的 “i”）	​https://api.minimax.chat

与 MCP 客户端搭配使用（推荐）

配置 MCP 客户端：

Claude Desktop

前往 Claude > Settings > Developer > Edit Config > claude_desktop_config.json 并添加：

{
  "mcpServers": {
    "minimax-mcp-js": {
      "command": "npx",
      "args": [
        "-y",
        "minimax-mcp-js"
      ],
      "env": {
        "MINIMAX_API_HOST": "<https://api.minimaxi.chat|https://api.minimax.chat>",
        "MINIMAX_API_KEY": "<your-api-key-here>",
        "MINIMAX_MCP_BASE_PATH": "<local-output-dir-path, such as /User/xxx/Desktop>",
        "MINIMAX_RESOURCE_MODE": "<optional, [url|local], url is default, audio/image/video are downloaded locally or provided in URL format>"
      }
    }
  }
}

Cursor

前往 Cursor → Preferences → Cursor Settings → MCP → Add new global MCP Server，添加上述配置。

⚠️ 注意：如果在 Cursor 中使用 MiniMax MCP JS 时遇到“No tools found”错误，请将 Cursor 更新到最新版本。更多信息请参阅此讨论帖。

就是这样。现在，你的 MCP 客户端可以通过这些工具与 MiniMax 交互。

本地开发：
在本地开发时，可以使用 npm link 测试更改：

# In your project directory
npm link

然后按照上文所示配置 Claude Desktop 或 Cursor 使用 npx。这样会自动使用你链接的版本。

⚠️ 注意：API 密钥必须与主机地址匹配。全球版和中国大陆版使用不同的主机：

• 全球主机：https://api.minimaxi.chat（注意多出的“i”）
• 中国大陆主机：https://api.minimaxi.chat

传输模式

MiniMax MCP JS 支持三种传输模式：

功能	stdio（默认）	REST	SSE
环境	仅本地	本地或云端部署	本地或云端部署
通信方式	通过 standard I/O	通过 HTTP requests	通过 server-sent events
使用场景	本地 MCP 客户端集成	API 服务、跨语言调用	需要服务端推送的应用
输入限制	支持 local files 或 URL 资源	云端部署时，建议使用 URL 输入	云端部署时，建议使用 URL 输入

配置

MiniMax-MCP-JS 提供多种灵活的配置方式，以适应不同的使用场景。配置优先级从高到低如下：

1. 请求参数配置（最高优先级）

在平台托管环境（如 ModelScope 或其他 MCP 平台）中，可以通过请求参数中的 meta.auth 对象为每个请求单独提供配置：

{
  "params": {
    "meta": {
      "auth": {
        "api_key": "your_api_key_here",
        "api_host": "<https://api.minimaxi.chat|https://api.minimaxi.chat>",
        "base_path": "/path/to/output",
        "resource_mode": "url"
      }
    }
  }
}

此方法支持多租户使用，每个请求都可以使用不同的 API 密钥和配置。

2. API 配置

在其他项目中将其作为模块使用时，可以通过 startMiniMaxMCP 函数传入配置：

import { startMiniMaxMCP } from 'minimax-mcp-js';

await startMiniMaxMCP({
  apiKey: 'your_api_key_here',
  apiHost: 'https://api.minimaxi.chat', // Global Host - https://api.minimaxi.chat, Mainland Host - https://api.minimax.chat
  basePath: '/path/to/output',
  resourceMode: 'url'
});

3. 命令行参数

1. 全局安装 CLI 工具：

# Install globally
pnpm install -g minimax-mcp-js

2. 将其作为 CLI 工具使用时，可以通过命令行参数提供配置：

minimax-mcp-js --api-key your_api_key_here --api-host https://api.minimaxi.chat --base-path /path/to/output --resource-mode url

4. 环境变量（最低优先级）

最基础的配置方式是通过环境变量配置：

# MiniMax API Key (required)
MINIMAX_API_KEY=your_api_key_here

# Base path for output files (optional, defaults to user's desktop)
MINIMAX_MCP_BASE_PATH=~/Desktop

# MiniMax API Host (optional, defaults to https://api.minimaxi.chat, Global Host - https://api.minimaxi.chat, Mainland Host - https://api.minimax.chat)
MINIMAX_API_HOST=https://api.minimaxi.chat

# Resource mode (optional, defaults to 'url')
# Options: 'url' (return URLs), 'local' (save files locally)
MINIMAX_RESOURCE_MODE=url

配置优先级

使用多种配置方式时，优先级顺序如下（从高到低）：

1. 请求级配置（通过每个 API 请求中的 meta.auth 设置）
2. 命令行参数
3. 环境变量
4. 配置文件
5. 默认值

这种优先级设置可确保适用于不同部署场景的灵活性，同时支持多租户环境下按请求配置。

配置参数

参数	描述	默认值
apiKey	MiniMax API 密钥	无（必填）
apiHost	MiniMax API 主机	全球主机 - https://api.minimaxi.chat，中国大陆主机 - https://api.minimax.chat
basePath	输出文件的基本路径	用户的桌面
resourceMode	资源处理模式，'url' 或 'local'	url

⚠️ 注意：API 密钥必须与主机地址匹配。全球版和中国大陆版使用不同的主机：

• 全球主机：https://api.minimaxi.chat（注意多出的“i”）
• 中国大陆主机：https://api.minimax.chat

使用示例

⚠️ 警告：使用这些工具可能会产生费用。

1. 播报一段晚间新闻

2. 克隆声音

3. 生成视频

4. 生成图像

5. 声音设计

可用工具

文本转音频

将文本转换为语音音频文件。

工具名称：text_to_audio

参数：

• text：要转换的文本（必填）
• model：模型版本，可选值为 'speech-02-hd'、'speech-02-turbo'、'speech-01-hd'、'speech-01-turbo'、'speech-01-240228'、'speech-01-turbo-240228'，默认值为 'speech-02-hd'
• voiceId：声音 ID，默认值为 'male-qn-qingse'
• speed：语速，范围为 0.5-2.0，默认值为 1.0
• vol：音量，范围为 0.1-10.0，默认值为 1.0
• pitch：音高，范围为 -12 至 12，默认值为 0
• emotion：情绪，可选值为 'happy'、'sad'、'angry'、'fearful'、'disgusted'、'surprised'、'neutral'，默认值为 'happy'。注意：此参数仅适用于 'speech-02-hd'、'speech-02-turbo'、'speech-01-turbo'、'speech-01-hd' 模型
• format：音频格式，可选值为 'mp3'、'pcm'、'flac'、'wav'，默认值为 'mp3'
• sampleRate：采样率（Hz），可选值为 8000、16000、22050、24000、32000、44100，默认值为 32000
• bitrate：比特率（bps），可选值为 64000、96000、128000、160000、192000、224000、256000、320000，默认值为 128000
• channel：音频声道数，可选值为 1 或 2，默认值为 1
• languageBoost：增强对指定语言和方言的识别能力。 支持的值包括： 'Chinese'、'Chinese,Yue'、'English'、'Arabic'、'Russian'、'Spanish'、'French'、'Portuguese'、'German'、'Turkish'、'Dutch'、'Ukrainian'、'Vietnamese'、'Indonesian'、'Japanese'、'Italian'、'Korean'、'Thai'、'Polish'、'Romanian'、'Greek'、'Czech'、'Finnish'、'Hindi'、'auto'，默认值为 'auto'
• stream：启用流式输出
• subtitleEnable：此参数用于控制是否启用字幕服务。模型必须为 'speech-01-turbo' 或 'speech-01-hd'。如果未提供此参数，默认值为 false
• outputDirectory：保存输出文件的目录。outputDirectory 相对于 MINIMAX_MCP_BASE_PATH（或配置中的 basePath）。最终保存路径为 ${basePath}/${outputDirectory}。例如，如果 MINIMAX_MCP_BASE_PATH=~/Desktop 且 outputDirectory=workspace，输出将保存到 ~/Desktop/workspace/。（可选）
• outputFile：保存输出文件的路径（可选；如果未提供，则自动生成）

播放音频

播放音频文件。支持 WAV 和 MP3 格式。不支持视频。

工具名称：play_audio

参数：

• inputFilePath：要播放的音频文件路径（必填）
• isUrl：音频文件是否为 URL，默认为 false

声音克隆

从音频文件克隆声音。

工具名称：voice_clone

参数：

• audioFile：音频文件路径（必填）
• voiceId：声音 ID（必填）
• text：演示音频的文本（可选）
• outputDirectory：保存输出文件的目录。outputDirectory 相对于 MINIMAX_MCP_BASE_PATH（或配置中的 basePath）。最终保存路径为 ${basePath}/${outputDirectory}。例如，如果 MINIMAX_MCP_BASE_PATH=~/Desktop 且 outputDirectory=workspace，则输出将保存到 ~/Desktop/workspace/。（可选）

文本生成图像

根据文本提示词生成图像。

工具名称：text_to_image

参数：

• prompt：图像描述（必填）
• model：模型版本，默认为 'image-01'
• aspectRatio：宽高比，默认为 '1:1'，可选值为 '1:1'、'16:9'、'4:3'、'3:2'、'2:3'、'3:4'、'9:16'、'21:9'
• n：要生成的图像数量，范围为 1-9，默认为 1
• promptOptimizer：是否优化提示词，默认为 true
• subjectReference：角色参考用的本地图像文件路径或公开 URL（可选）
• outputDirectory：保存输出文件的目录。outputDirectory 相对于 MINIMAX_MCP_BASE_PATH（或配置中的 basePath）。最终保存路径为 ${basePath}/${outputDirectory}。例如，如果 MINIMAX_MCP_BASE_PATH=~/Desktop 且 outputDirectory=workspace，则输出将保存到 ~/Desktop/workspace/。（可选）
• outputFile：保存输出文件的路径（可选；如果未提供，则自动生成）
• asyncMode：是否使用异步模式。默认为 False。如果为 True，视频生成任务将异步提交，响应会返回 task_id。应使用 query_video_generation 工具检查任务状态并获取结果。（可选）

生成视频

根据文本提示词生成视频。

工具名称：generate_video

参数：

• prompt：视频描述（必填）
• model：模型版本，可选值为 'T2V-01'、'T2V-01-Director'、'I2V-01'、'I2V-01-Director'、'I2V-01-live'、'S2V-01'、'MiniMax-Hailuo-02'，默认为 'MiniMax-Hailuo-02'
• firstFrameImage：首帧图像路径（可选）
• duration：视频时长。模型必须为 "MiniMax-Hailuo-02"。取值为 6 和 10。（可选）
• resolution：视频分辨率。模型必须为 "MiniMax-Hailuo-02"。可选值为 ["768P", "1080P"]。（可选）
• outputDirectory：保存输出文件的目录。outputDirectory 相对于 MINIMAX_MCP_BASE_PATH（或配置中的 basePath）。最终保存路径为 ${basePath}/${outputDirectory}。例如，如果 MINIMAX_MCP_BASE_PATH=~/Desktop 且 outputDirectory=workspace，则输出将保存到 ~/Desktop/workspace/。（可选）
• outputFile：保存输出文件的路径（可选；如果未提供，则自动生成）
• asyncMode：是否使用异步模式。默认为 False。如果为 True，视频生成任务将异步提交，响应会返回 task_id。应使用 query_video_generation 工具检查任务状态并获取结果。（可选）

查询视频生成状态

查询视频生成任务的状态。

工具名称：query_video_generation

参数：

• taskId：要查询的任务 ID。如果 async_mode 为 True，应使用 generate_video 工具返回的 task_id。（必填）
• outputDirectory：保存输出文件的目录。outputDirectory 相对于 MINIMAX_MCP_BASE_PATH（或配置中的 basePath）。最终保存路径为 ${basePath}/${outputDirectory}。例如，如果 MINIMAX_MCP_BASE_PATH=~/Desktop 且 outputDirectory=workspace，则输出将保存到 ~/Desktop/workspace/。（可选）

语音设计

根据描述提示词生成语音。

工具名称：voice_design

参数：

• prompt：用于生成语音的提示词。（必填）
• previewText：用于试听语音的文本。（必填）
• voiceId：要使用的语音 ID。例如，"male-qn-qingse"/"audiobook_female_1"/"cute_boy"/"Charming_Lady"...（可选）
• outputDirectory：输出文件的保存目录。outputDirectory 相对于 MINIMAX_MCP_BASE_PATH（或配置中的 basePath）。最终保存路径为 ${basePath}/${outputDirectory}。例如，如果 MINIMAX_MCP_BASE_PATH=~/Desktop 且 outputDirectory=workspace，则输出将保存到 ~/Desktop/workspace/。（可选）

常见问题

1. 如何在异步模式下使用 generate_video

开始前定义完成规则： 或者，也可以在 IDE 设置中配置这些规则（例如，Cursor）：

开发

设置

# Clone the repository
git clone https://github.com/MiniMax-AI/MiniMax-MCP-JS.git
cd minimax-mcp-js

# Install dependencies
pnpm install

构建

# Build the project
pnpm run build

运行

# Run the MCP server
pnpm start

许可证

MIT