!export

文档

- English Documentation
- Python 版本 - MiniMax MCP的官方Python实现

更新日志

$3

#### 🔧 修复与优化
- TTS工具修复: 修复了 text_to_audio 工具中 languageBoost 和 subtitleEnable 参数的处理问题
- API响应增强: TTS API 可以返回音频文件(audio)和字幕文件(subtitle_file)，提供更完整的语音转文字体验

$3

#### 🆕 新增功能
- 音色设计: 新增 voice_design 工具 - 根据描述性提示词创建自定义音色并生成试听音频
- 视频生成增强: 新增 MiniMax-Hailuo-02 模型，支持超清画质和时长/分辨率控制
- 音乐生成: 采用 music-1.5 模型增强 music_generation 工具

#### 📈 功能增强
- voice_design - 根据文本描述生成个性化音色
- generate_video - 现在支持 MiniMax-Hailuo-02 模型，可选择 6s/10s 时长和 768P/1080P 分辨率
- music_generation - 采用 music-1.5 模型进行高质量音乐创作

功能特性

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

安装

``bash


使用 pnpm 安装（推荐）


pnpm add minimax-mcp-js
`

快速开始

MiniMax MCP JS 实现了 Model Context Protocol (MCP) 规范，可以作为服务器与支持 MCP 的客户端（如 Claude AI）进行交互。

$3

1. 从MiniMax国内开放平台或MiniMax国际开放平台获取您的 API 密钥。
2. 确保你已经安装了 Node.js 和 npm
3. 重要提示: API的服务器地址和密钥在不同区域有所不同，两者需要匹配，否则会有 invalid api key 的错误

|地区| 国际 | 国内 |
|:--|:-----|:-----|
|MINIMAX_API_KEY| 获取密钥 MiniMax国际版 | 获取密钥 MiniMax |
|MINIMAX_API_HOST| ​https://api.minimaxi.chat （请注意额外的 "i" 字母） | ​https://api.minimax.chat |

$3

在 MCP 客户端中配置：

#### Claude Desktop

进入 Claude > Settings > Developer > Edit Config > claude_desktop_config.json 添加如下配置:

`json
{
"mcpServers": {
"minimax-mcp-js": {
"command": "npx",
"args": [
"-y",
"minimax-mcp-js"
],
"env": {
"MINIMAX_API_HOST": "https://api.minimax.chat",
"MINIMAX_API_KEY": "<您的API密钥>",
"MINIMAX_MCP_BASE_PATH": "<本地输出目录路径，如/User/xxx/Desktop>",
"MINIMAX_RESOURCE_MODE": "<可选配置，资源生成后的提供方式, [url|local], 默认为 url>"
}
}
}
}
`

#### Cursor

进入 Cursor → Preferences → Cursor Settings → MCP → Add new global MCP Server 添加上述配置。

⚠️ 注意: 如果您在 Cursor 中使用 MiniMax MCP JS 时遇到 "No tools found" 错误，请将 Cursor 升级到最新版本。
更多信息，请参阅这个讨论帖.

完成以上步骤后，您的MCP客户端就可以通过这些工具与MiniMax进行交互了。

本地开发:
在本地开发时，您可以使用 npm link 来测试您的更改：
`bash


在您的项目目录中


npm link
`

⚠️ 注意：API密钥需要与主机地址匹配，在国际版和中国大陆版使用不同的主机地址：
- 全球版主机地址: https://api.minimaxi.chat (注意多了一个 "i")
- 中国大陆版主机地址: https://api.minimax.chat

传输模式

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

| 特性 | stdio (默认) | REST | SSE |
|:-----|:-----|:-----|:-----|
| 运行环境 | 本地运行 | 可本地或云端部署 | 可本地或云端部署 |
| 通信方式 | 通过标准输入输出通信 | 通过HTTP请求通信 | 通过服务器发送事件通信 |
| 适用场景 | 本地MCP客户端集成 | API服务，跨语言调用 | 需要服务器推送的应用 |
| 输入限制 | 支持处理本地文件或有效的URL资源 | 当部署在云端时，建议使用URL作为输入 | 当部署在云端时，建议使用URL作为输入 |




配置方式

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

$3

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

`json
{
"params": {
"meta": {
"auth": {
"api_key": "您的API密钥",
"api_host": "https://api.minimax.chat",
"base_path": "/输出路径",
"resource_mode": "url"
}
}
}
}
`

这种方式允许多租户使用，每个请求可以使用不同的API密钥和配置。

$3

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

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

await startMiniMaxMCP({
apiKey: '您的API密钥',
apiHost: 'https://api.minimax.chat',
basePath: '/输出路径',
resourceMode: 'url'
});
`

$3

1. 全局安装 CLI 工具：
`bash


全局安装


pnpm install -g minimax-mcp-js
`

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

`bash
minimax-mcp-js --api-key 您的API密钥 --api-host https://api.minimax.chat --base-path /输出路径 --resource-mode url
`

$3

最基本的配置方式，通过环境变量提供：

`bash


MiniMax API 密钥 (必需)

MINIMAX_API_KEY=您的API密钥

输出文件的基础路径 (可选，默认为用户桌面)

MINIMAX_MCP_BASE_PATH=~/Desktop

MiniMax API 主机 (可选，默认为 https://api.minimax.chat)

MINIMAX_API_HOST=https://api.minimax.chat

资源模式 (可选，默认为 'url')

选项: 'url' (返回URL), 'local' (本地保存文件)

MINIMAX_RESOURCE_MODE=url
`

配置优先级

当使用多种配置方式时，将按照以下优先级顺序应用（从高到低）：

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

这种优先级设计确保了在不同部署场景下的灵活性，同时为多租户环境提供了按请求配置的能力。

配置项说明

| 配置项 | 描述 | 默认值 |
|-------|------|--------|
| apiKey | MiniMax API 密钥 | 无（必填） |
| apiHost | MiniMax API 主机地址 | https://api.minimax.chat |
| basePath | 输出文件的基础路径 | 用户桌面 |
| resourceMode | 资源处理模式，'url' 或 'local' | url |

⚠️ 注意：API密钥需要与主机地址匹配，在国际版和中国大陆版使用不同的主机地址：
- 全球版主机地址: https://api.minimaxi.chat (注意多了一个 "i")
- 中国大陆版主机地址: https://api.minimax.chat




使用示例

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

$3

$3

$3

$3

$3

$3

可用工具

$3

将文本转换为语音文件。

工具名称：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: 增强对指定的小语种和方言的识别能力，设置后可以提升在指定小语种/方言场景下的语音表现。如果不明确小语种类型，则可以选择"auto"，模型将自主判断小语种类型。支持以下取值：
'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: 保存输出文件的路径 (可选，如果未提供则自动生成)

$3

从音频文件克隆语音。

工具名称：voice_clone

参数：
- audioFile: 音频文件路径 (必需)
- voiceId: 语音 ID (必需)
- text: 演示音频的文本 (可选)
- outputDirectory: 保存输出文件的目录。 outputDirectory 是相对于 MINIMAX_MCP_BASE_PATH（或配置中的 basePath）的。最终的保存路径是 ${basePath}/${outputDirectory}, 例如, 如果 MINIMAX_MCP_BASE_PATH=~/Desktop 且 outputDirectory=workspace，则输出将被保存到 ~/Desktop/workspace/ (可选)

$3

列出所有可用的文本转语音声音。仅在 api_host 为 https://api.minimax.chat 时支持。

工具名称：list_voices

参数：
- voiceType: 要列出的语音类型，选项为 'all'（全部）, 'system'（系统）, 'voice_cloning'（克隆语音），默认为 'all'

$3

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

工具名称：play_audio

参数：
- inputFilePath: 要播放的音频文件路径 (必需)
- isUrl: 音频文件是否为 URL，默认为 false

$3

根据文本提示生成图像。

工具名称：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: 保存输出文件的路径 (可选，如果未提供则自动生成)

$3

根据文本提示生成视频。

工具名称：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，视频生成任务将异步提交并返回任务 ID。需要使用 query_video_generation 工具来检查任务状态并获取结果。(可选)

$3

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

工具名称：query_video_generation

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

$3

根据提示和歌词生成音乐。

工具名称：music_generation

参数：
- prompt: 音乐创作灵感，描述风格、情绪、场景等。例如："流行音乐，悲伤，适合雨夜"。字符范围：[10, 300]。(必需)
- lyrics: 用于音乐生成的歌词。使用换行符 (\\n) 分隔每行歌词。支持歌词结构标签 [Intro] [Verse] [Chorus] [Bridge] [Outro] 以增强音乐性。字符范围：[10, 600]（每个中文字符、标点符号和字母计为1个字符）。(必需)
- sampleRate: 生成音乐的采样率。值：[16000, 24000, 32000, 44100]，默认为 32000。(可选)
- bitrate: 生成音乐的比特率。值：[32000, 64000, 128000, 256000]，默认为 128000。(可选)
- format: 生成音乐的格式。值：["mp3", "wav", "pcm"]，默认为 'mp3'。(可选)
- outputDirectory: 保存输出文件的目录。 outputDirectory 是相对于 MINIMAX_MCP_BASE_PATH（或配置中的 basePath）的。最终的保存路径是 ${basePath}/${outputDirectory}, 例如, 如果 MINIMAX_MCP_BASE_PATH=~/Desktop 且 outputDirectory=workspace，则输出将被保存到 ~/Desktop/workspace/ (可选)




$3

根据描述提示生成音色。

工具名称：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/ (可选)

常见问题

$3

在对话开始之前定义完成规则：

或者，可以在你的本地客户端的配置中设置这些规则（例如 Cursor）：

开发

$3

`bash


克隆仓库

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

安装依赖

pnpm install
`

$3

`bash


构建项目


pnpm run build
`

$3

`bash


运行 MCP 服务器


pnpm start
``

许可证

MIT