跳转到主要内容

模型上下文协议(MCP)简介

模型上下文协议(MCP) 是一个开放协议,标准化应用程序向大语言模型提供工具和上下文的方式。它类似于 AI 领域的 USB‑C 接口,提供一个稳定和标准化的接入点,让模型能访问数据库、API、插件或其他工具。通过 MCP 工具,开发者可以让模型访问托管在远程 MCP 服务器上的各种工具。 MiniMax 提供官方的 Python 版本JavaScript 版本 模型上下文协议(MCP)、声音克隆、图像生成、视频生成等多模态能力。 开发者可自行部署 MCP 服务,并通过 MCP 客户端(如 Claude Desktop、Cursor、Windsurf、OpenAI Agents 等)调用,从而快速集成语音、图像和视频相关功能。在传输方面,Python 版本提供 stdio 和 SSE 两种标准传输方式,JS 版本提供 stdio 、REST 和 SSE 三种标准传输方式。

MiniMax MCP 工具和参数介绍

MCP 工具清单

text_to_audio

该工具可将将输入的文本合成为自然流畅的语音

list_voices

该工具可查询所有可用音色

voice_clone

该工具可根据指定音频文件克隆音色

voice_design

该工具可根据指定提示词生成音色和试听文本

play_audio

该工具用于播放一个音频文件

music_generation

该工具可根据指定提示词和歌词生成音乐

generate_video

该工具可根据指定文本或图片进行视频生成生成

image_to_video

该工具用于使用首帧图像生成视频

query_video_generation

该工具用于查询异步视频生成任务的状态

text_to_image

该工具可根据指定提示词生成图片

工具与参数详情

1. text_to_audio

该工具可将输入的文本合成为自然流畅的语音。
参数含义格式及说明默认值
text必需,待合成的文本字符串,长度限制 < 10000 字符,段落切换用换行符替代。
output_directory保存音频文件的目录字符串 (文件路径)配置文件中设置的路径
voice_id请求的音色编号字符串,可选值可参考 API 手册"female-shaonv"
model请求的模型版本字符串,可选值可参考 API 手册"speech-02-hd"
speed生成音频的语速浮点数,范围 [0.5 - 2.0]1.0
vol生成音频的音量浮点数,范围1.0
pitch生成音频的音调整数,范围 [-12,12]0 (原音色输出)
emotion控制合成语音的情绪字符串,可选值范围["happy", "sad", "angry", "fearful", "disgusted", "surprised", "calm"],该参数仅对 speech-02-hd, speech-02-turbo, speech-01-turbo, speech-01-hd 模型生效happy
sample_rate生成音频的采样率整数,可选范围 [8000, 16000, 22050, 24000, 32000, 44100]32000
bitrate生成音频的比特率整数,可选范围 [32000, 64000, 128000, 256000],该参数仅对 mp3 格式的音频生效128000
channel生成音频的声道数整数,可选值为 1:单声道, 2:双声道1
format生成的音频文件格式字符串,可选范围["pcm", "mp3", "flac", "wav"],其中,“wav” 仅在非流式传输下支持mp3
language_boost语言增强选项,提升在指定小语种或方言场景下的语音表现字符串,可选值可参考 API 手册null

2. list_voices

该工具可查询所有可用音色
参数含义格式及说明默认值
voice_type需要查询的音色类型。字符串, 可选值范围 [“system” (系统音色) , “voice_cloning” (快速复刻的音色) , “voice_generation” (文生音色接口生成的音色) , “music_generation” (音乐生成产生的人声或者伴奏音色) , “all” (以上全部) ]“all”

3. voice_clone

该工具可根据指定音频文件克隆音色
参数含义格式及说明默认值
voice_id必需, 音色复刻的声音编号字符串, 可自定义, 注意事项包括 1. 自定义的 voice_id 长度范围 2. 首字符必须为英文字母 3. 允许数字、字母、-、_4. 末位字符不可为-、_5. 创建的 voice_id 不可与之前重复
file必需, 用于克隆的音频文件字符串, 可选范围[“mp3”, “m4a”, “wav”]
text生成克隆音色演示音频的文本字符串, 限制 2000 字符以内
output_directory保存音频文件的目录字符串 (文件路径)配置文件中设置的路径
is_url用于克隆的音频文件来源是否 url布尔值 (True / False)FALSE

4. voice_design

该工具可根据指定提示词生成音色和试听文本
参数含义格式及说明默认值
prompt必需, 生成音色的描述字符串
preview_text必需, 生成试听音频的文本字符串
voice_id自定义生成音色的 ID字符串自动生成唯一值
output_directory保存试听音频文件的目录字符串 (文件路径)配置文件中设置的路径

5. play_audio

该工具用于播放一个音频文件。
参数含义格式及说明默认值
input_file_path必需, 要播放的音频文件的本地路径或 URL字符串 (文件路径或 URL)
is_url需要播放的音频文件来源是否 url布尔值 (True / False)FALSE

6. music_generation

该工具可根据指定提示词和歌词生成音乐
参数含义可选值/格式默认值
prompt必需, 表示音乐创作的灵感,通常是对音乐风格、情绪、场景等的描述字符串, 字符取值范围 [10-300]
lyrics必需, 音乐生成的歌词字符串, 使用换行符 (\n) 分隔每行歌词, 支持结构标签 [Intro][Verse][Chorus][Bridge][Outro], 字符取值范围
sample_rate生成音乐的采样率整数, 可选值范围32000
bitrate生成音乐的比特率整数, 可选值范围128000
format生成音乐的格式字符串, 可选值范围 [“mp3”, “wav”, “pcm”]“mp3”
output_directory保存音乐文件的目录字符串 (文件路径)配置文件中设置的路径

7. generate_video

该工具可根据指定提示词生成视频, promptfirst_frame_image 两个参数至少要有一个。
参数含义格式及说明默认值
prompt生成视频的描述字符串, 最大支持 2000 字符
model请求的模型版本字符串, 可选范围 MiniMax-Hailuo-02, T2V-01-Director, I2V-01-Director, S2V-01, I2V-01-live, I2V-01, T2V-01T2V-01
first_frame_image视频的首帧画面支持传入图片的 “data:image/jpeg;base64,data” 格式的 Base64 编码字符串, 或可通过公网访问的 URL
duration生成视频的持续时间 (秒)整数, 可选值, 与分辨率和模型相关:
01 系列 (包括 T2V-01, I2V-01,T2V-01-Director, I2V-01-Director, I2V-01-live, S2V-01): 可选值: 6
02 系列 (MiniMax-Hailuo-02) : 512P: 可选值: 6, 10 768P: 可选值: 6, 10 1080P: 可选值: 6
6
resolution生成视频的分辨率字符串, 与选择模型及设置的视频时长相关:
01 系列 (包括 T2V-01, I2V-01,T2V-01-Director, I2V-01-Director, I2V-01-live, S2V-01): 不支持设置本参数。
02 系列
6s 时长: 默认值为”720P”, 可选范围 ["512P", "768P", "1080P"]
10s 时长: 默认值”768P”, 可选范围 ["512P", "768P"]
None
output_directory保存视频文件的目录字符串 (文件路径)配置文件中设置的路径
async_mode是否使用异步模式, 启用则返回任务 ID布尔值 (True / False)FALSE

8. image_to_video

该工具用于使用首帧图像生成视频, 其中 promptfirst_frame_image 两个参数至少有其一, 该 MCP 工具仅在 JavaScript/TypeScript 版本中可用
参数含义格式及说明默认值
prompt必需, 生成视频的描述。字符串, 最大支持 2000 字符
model请求的模型版本字符串, 可选范围 [“MiniMax-Hailuo-02”, “T2V-01-Director”, “I2V-01-Director”, “S2V-01”, “I2V-01-live”, “I2V-01”, “T2V-01”]“T2V-01”
first_frame_image必需, 视频的首帧画面支持传入图片的 “data:image/jpeg;base64,data” 格式的 Base64 编码字符串, 或可通过公网访问的 URL
output_directory保存视频文件的目录字符串 (文件路径)配置文件中设置的路径
async_mode是否使用异步模式, 启用则返回任务 ID布尔值 (True / False)FALSE

9. query_video_generation

该工具用于查询异步视频生成任务的状态。
参数含义格式及说明默认值
task_id必需, 需要查询的任务 ID字符串
output_directory保存视频文件的目录字符串 (文件路径)配置文件中设置的路径

10. text_to_image

该工具可根据指定提示词生成图片
参数含义格式及说明默认值
prompt必需, 生成图像的描述字符串, 最大支持 1500 字符
model请求的模型版本字符串, 可选范围 [“image-01”, “image-01-live”]“image-01”
aspect_ratio生成图像的宽高比字符串, 可选范围 [“1:1”, “16:9”, “4:3”, “3:2”, “2:3”, “3:4”, “9:16”, “21:9”]“1:1”
n单次请求生成的图片数量整数, 可选范围1
prompt_optimizer是否开启提示词自动优化提示词布尔值 (True / False)TRUE
output_directory保存图片文件的目录字符串 (文件路径)配置文件中设置的路径

在客户端使用 MiniMax MCP 服务

获取 API Key

  • 访问 MiniMax 开放平台
  • 点击“Create new secret key”按钮,输入项目名称以创建新的 API Key。
  • 创建成功后,系统将展示 API Key。请务必复制并妥善保存,该密钥只会显示一次,无法再次查看。
获取 API Key

UVX 安装和配置

MiniMax‑MCP 是一个 Python 实现的 MCP 服务,为了让 MCP 客户端顺利调用,该服务必须通过 uvx 启动和执行。 uvxuv 提供的命令行工具,类似于 npm exec ,用于运行包内部定义的可执行程序,确保环境隔离与依赖可控。
  1. 安装 uv 以便获取 uvx
    • macOS / Linux 用户:
curl -LsSf https://astral.sh/uv/install.sh | sh
  • Windows 用户:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
其他安装方式可参考 uv 仓库。安装完成后,会在 Python 环境的 Scriptsbin 目录中生成 uvuvx 可执行文件。
  1. 验证 uvx 是否可用
执行命令:
  • macOS / Linux 用户:
which uvx
  • Windows 用户:
(Get-Command uvx).source
  • 若正确安装,会显示路径(如 /usr/local/bin/uvx )。
  • 若系统报错 spawn uvx ENOENT ,说明没有安装 uvxuvx 不在系统路径中,需要配置绝对路径。

传输方式说明

MiniMax-MCP 提供 studio 和 SSE 两种传输方式,在使用时可按需选择
特性stdio(默认)SSE(Server‑Sent Events)
运行环境本地部署运行本地部署或云端部署均可
通信方式通过 stdout 进行通信通过网络通信
适用场景本地 MCP 客户端集成需要服务器推送的应用
输入资源支持支持本地文件或有效的 URL 资源支持本地文件或 URL;部署在云端时推荐使用 URL 输入

在 Claude Desktop 中使用

  1. Claude 官网下载 Claude Desktop
  2. 前往 Claude > Settings > Developer > Edit Config > claude_desktop_config.json ,添加以下配置。完成配置后,重启 Claude Desktop。
注意:如果使用 Windows,需要在 Claude Desktop 中启用”开发者模式”才能使用 MCP 服务器。 若出现报错 spawn uvx ENOENT ,请在 command 中配置 uvx 的绝对路径
{
  "mcpServers": {
    "MiniMax": {
      "command": "uvx",
      "args": ["minimax-mcp"],
      "env": {
        "MINIMAX_API_KEY": "填写你的API密钥",
        "MINIMAX_MCP_BASE_PATH": "本地输出目录路径,如/User/xxx/Desktop",
        "MINIMAX_API_HOST": "填写API Host, https://api.minimaxi.com 或 https://api.minimax.io",
        "MINIMAX_API_RESOURCE_MODE": "可选配置,资源生成后的提供方式, 可选项为 [url|local], 默认为 url"
      },
      "transport": "可选配置,传输方式,可选项为 [studio|SSE],默认为 studio"
    }
  }
}

在 Cursor 中使用

  1. 通过 Cursor 官网 下载并安装 Cursor
  2. 前往 Cursor -> Preferences -> Cursor Settings -> Tools & Inrgrations -> MCP -> Add Custom MCP ,打开 MCP 工具配置文件
Cursor MCP 配置
  1. mcp.json 文件中,增加 MiniMax 账户配置信息
{
  "mcpServers": {
    "MiniMax": {
      "command": "uvx",
      "args": ["minimax-mcp"],
      "env": {
        "MINIMAX_API_KEY": "填写你的API密钥",
        "MINIMAX_MCP_BASE_PATH": "本地输出目录路径,如/User/xxx/Desktop,需要保证路径存在且具有写入权限",
        "MINIMAX_API_HOST": "填写API Host, https://api.minimaxi.com 或 https://api.minimax.io",
        "MINIMAX_API_RESOURCE_MODE": "可选配置,资源生成后的提供方式, 可选项为 [url|local], 默认为 url"
      },
      "transport": "可选配置,传输方式,可选项为 [studio|SSE],默认为 studio"
    }
  }
}

在 Cherry Studio 中使用

  1. 通过 Cherry Studio 官网 下载客户端
  2. 前往 Settings -> MCP Settings -> Add Server -> Import from JSON ,将以下代码粘贴到代码框中,确认
{
      "name": "minimax-mcp",
      "isActive": true,
      "command": "uvx",
      "args": [
        "minimax-mcp"
      ],
      "env": {
        "MINIMAX_API_KEY": "填写你的API密钥",
        "MINIMAX_MCP_BASE_PATH": "本地输出目录路径,如/User/xxx/Desktop,需要保证路径存在且具有写入权限",
        "MINIMAX_API_HOST": "填写API Host, https://api.minimaxi.com 或 https://api.minimax.io",
        "MINIMAX_API_RESOURCE_MODE": "可选配置,资源生成后的提供方式, 可选项为 [url|local], 默认为 url"
      }
      "transport": "可选配置,传输方式,可选项为 [studio|SSE],默认为 studio"
    }
  1. 在对话框中,点击 MCP Settings 后,选择完成配置的“MiniMax MCP”即可使用
Cherry Studio 配置

在客户端使用 MiniMax MCP JS 服务器

获取 API Key

  • 访问 MiniMax 开放平台
  • 点击“Create new secret key”按钮,输入项目名称以创建新的 API Key。
  • 创建成功后,系统将展示 API Key。请务必复制并妥善保存,该密钥只会显示一次,无法再次查看。
获取 API Key

Node.js 与 npm 安装

Node.js 是一个开源的 JavaScript 运行时环境,可以在浏览器之外运行 JavaScript 代码。它基于 Google 的 V8 引擎,具有高性能、事件驱动和非阻塞 I/O 的特点,适合构建高并发的网络服务、实时应用和微服务等场景。 npm 是随 Node.js 一起安装的默认包管理器,也是全球最大的软件注册中心。开发者可以通过 npm 搜索、安装、更新和管理依赖包(包括前端和后端代码模块),大幅简化开发流程。
  1. 安装 Node.js 与 npm
  2. 验证安装是否完成
执行以下命令,若正确安装,会显示 Node.js 和 npm 的版本
node -v
npm -v

传输方式说明

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

在 Claude Desktop 中使用

  1. 在 Claude 官网下载 Claude Desktop
  2. 前往 Claude > Settings > Developer > Edit Config > claude_desktop_config.json ,添加以下配置。完成配置后,重启 Claude Desktop。
注意:如果使用 Windows,需要在 Claude Desktop 中启用”开发者模式”才能使用 MCP 服务器。
{
  "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>"
      },
      "transport": "可选配置,传输方式,可选项为 [studio|REST|SSE],默认为 studio"
    }
  }
}

在 Cursor 中使用

  1. 通过 Cursor 官网 下载并安装 Cursor
  2. 前往 Cursor -> Preferences -> Cursor Settings -> Tools & Inrgrations -> MCP -> Add Custom MCP ,打开 MCP 工具配置文件
Cursor MCP 配置
  1. mcp.json 文件中,增加 MiniMax 账户配置信息
{
  "mcpServers": {
    "MiniMax": {
      "command": "uvx",
      "args": ["minimax-mcp"],
      "env": {
        "MINIMAX_API_KEY": "填写你的API密钥",
        "MINIMAX_MCP_BASE_PATH": "本地输出目录路径,如/User/xxx/Desktop,需要保证路径存在且具有写入权限",
        "MINIMAX_API_HOST": "填写API Host, https://api.minimaxi.com 或 https://api.minimax.io",
        "MINIMAX_API_RESOURCE_MODE": "可选配置,资源生成后的提供方式, 可选项为 [url|local], 默认为 url"
      },
      "transport": "可选配置,传输方式,可选项为 [studio|REST|SSE],默认为 studio"
    }
  }
}
  1. 完成配置后,可以查看 MiniMax 目前支持的 mcp 工具
MCP 工具列表

在 Cherry Studio 中使用

  1. 通过 Cherry Studio 官网 下载客户端
  2. 前往 Settings -> MCP Settings -> Add Server -> Import from JSON ,将以下代码粘贴到代码框中,确认
{
  "name": "minimax-mcp",
  "isActive": true,
  "command": "npx",
  "args": ["y", "minimax-mcp"],
  "env": {
    "MINIMAX_API_KEY": "填写你的API密钥",
    "MINIMAX_MCP_BASE_PATH": "本地输出目录路径,如/User/xxx/Desktop,需要保证路径存在且具有写入权限",
    "MINIMAX_API_HOST": "填写API Host, https://api.minimaxi.com 或 https://api.minimax.io",
    "MINIMAX_API_RESOURCE_MODE": "可选配置,资源生成后的提供方式, 可选项为 [url|local], 默认为 url"
  },
  "transport": "可选配置,传输方式,可选项为 [studio|REST|SSE],默认为 studio"
}
  1. 在对话框中,点击 MCP Settings 后,选择完成配置的“MiniMax MCP”即可使用
Cherry Studio 配置

MiniMax MCP 使用示例

音频工具使用

  1. 选择合适的声音信息,播报晚间新闻片段
参考提示词
choose a voice, and broadcast a segment of the evening news
生成内容 思考过程 思考过程
  1. 根据指定音频克隆声音,并指定克隆音色的 id
参考提示词
clone the voice from the audio file named Marketing_Voice.sav, the id is test_vlone_voice
来源音频 结果音频 思考过程 思考过程
  1. 按照要求设计音色,并给定示例文本生成音频
参考提示词
Design a voice, the requirement is "Mysterious narrator with a deep, magnetic voice, suspenseful tone, moderate pace, subtle reverb". Then use it in the sample Text: "In the shadows of the old manor, secrets whisper through the walls. Beware what you seek…"
生成内容 思考过程 思考过程

音乐生成工具使用

参考提示词
generate a song, the background music is gentle ambient piano and warm pad synth, soft reverb and subtle field recordings of wind chimes. The musical style: calm and reflective
Lyrics:
‘In the stillness of the midnight air,
Find the echoes of dreams we share.
Softly drifting ‘neath pale moonlight,
Whispering hearts drifting into night.’"
生成内容 思考过程 思考过程

图片生成工具使用

参考提示词
generate a hyperreal style picture, the requirement is "Ultra‑detailed digital painting of a serene mountain lake at sunrise, ultra-realistic, soft golden light, mist over the water"
生成内容 生成的图片 思考过程 思考过程

视频生成工具使用

参考提示词及图片
From the existing image of a kitten perched on a diving board, create a short video showing the kitten crouching, leaping off into the pool, and making a small splash—adorable and playful. Use MiniMax-Hailuo-02 model, and resolution is 1080P
输入图片 生成内容 思考过程 思考过程

如何做出自己的贡献

若希望对 MiniMax MCP 项目进行改进或修复错误,欢迎通过以下方式提交建议或代码贡献:
  1. 在 GitHub 项目主页( Python 版JS 版 )开一个新的 Issue,简要描述您建议的更改或问题。
  2. 获取反馈后,请按照项目贡献指南创建一个对应的 Pull Request (PR) ,附上修改说明及必要的背景信息。
  3. 项目维护者会对你的 PR 进行代码审查,并给予合并建议或进一步修改意见。
I