MiniMax MCP JS

Documentación

• 中文文档
• Versión en Python - Implementación oficial en Python de MiniMax MCP

Notas de la versión

22 de julio de 2025

🔧 Correcciones y mejoras

• Correcciones de la herramienta TTS: Se corrigió el manejo de parámetros para languageBoost y subtitleEnable en la herramienta text_to_audio
• Mejora de la respuesta de la API: La API de TTS puede devolver tanto el archivo de audio como el archivo de subtítulos, proporcionando una experiencia de voz a texto más completa

7 de julio de 2025

🆕 Novedades

• Diseño de voz: Nueva herramienta voice_design: crea voces personalizadas a partir de indicaciones descriptivas con audio de vista previa
• Mejora de video: Se agregó el modelo MiniMax-Hailuo-02 con calidad ultra nítida y controles de duración/resolución

📈 Herramientas mejoradas

• voice_design: Genera voces personalizadas a partir de descripciones de texto
• generate_video: Ahora es compatible con MiniMax-Hailuo-02 con opciones de duración de 6s/10s y resolución de 768P/1080P

Características

• Texto a voz (TTS)
• Generación de imágenes
• Generación de videos
• Clonación de voz
• Diseño de voz
• Configuración dinámica (admite tanto variables de entorno como parámetros de solicitud)
• Compatible con el alojamiento de plataformas MCP (ModelScope y otras plataformas MCP)

Instalación

Instalación mediante Smithery

Para instalar MiniMax MCP JS para Claude Desktop automáticamente mediante Smithery:

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

Instalación manual

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

Inicio rápido

MiniMax MCP JS implementa la especificación del Protocolo de Contexto de Modelo (MCP) y se puede usar como servidor para interactuar con clientes compatibles con MCP (como Claude AI).

Inicio rápido con el cliente MCP

1. Obtén tu clave de API desde Plataforma Internacional de MiniMax.
2. Asegúrate de tener instalados Node.js y npm
3. Importante: el HOST y la CLAVE de la API son diferentes en cada región, deben coincidir; de lo contrario, recibirás un error Invalid API key.

Región	Global	China continental
MINIMAX_API_KEY	obténla en MiniMax Global	obténla en MiniMax
MINIMAX_API_HOST	​https://api.minimaxi.chat (nota la "i" adicional)	​https://api.minimax.chat

Uso con clientes MCP (recomendado)

Configura tu cliente MCP:

Claude Desktop

Ve a Claude > Settings > Developer > Edit Config > claude_desktop_config.json para incluir:

{
  "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

Ve a Cursor → Preferences → Cursor Settings → MCP → Add new global MCP Server para agregar la configuración anterior.

⚠️ Nota: Si encuentras un error de "No se encontraron herramientas" al usar MiniMax MCP JS con Cursor, actualiza Cursor a la versión más reciente. Para más información, consulta este hilo de discusión.

Eso es todo. Tu cliente MCP ahora puede interactuar con MiniMax a través de estas herramientas.

Para desarrollo local: Cuando desarrolles localmente, puedes usar npm link para probar tus cambios:

# In your project directory
npm link

Luego configura Claude Desktop o Cursor para usar npx como se muestra arriba. Esto usará automáticamente tu versión vinculada.

⚠️ Nota: La clave de API debe coincidir con la dirección del host. Se usan hosts diferentes para las versiones global y de China continental:

• Host global: https://api.minimaxi.chat (nota la "i" adicional)
• Host de China continental: https://api.minimaxi.chat

Modos de transporte

MiniMax MCP JS admite tres modos de transporte:

Característica	stdio (predeterminado)	REST	SSE
Entorno	Solo local	Local o implementación en la nube	Local o implementación en la nube
Comunicación	Mediante standard I/O	Mediante HTTP requests	Mediante server-sent events
Casos de uso	Integración con cliente MCP local	Servicios de API, llamadas entre lenguajes	Aplicaciones que requieren push del servidor
Restricciones de entrada	Admite recursos local files o URL	Cuando se implementa en la nube, se recomienda entrada URL	Cuando se implementa en la nube, se recomienda entrada URL

Configuración

MiniMax-MCP-JS proporciona múltiples métodos de configuración flexibles para adaptarse a diferentes casos de uso. La prioridad de configuración de mayor a menor es la siguiente:

1. Configuración por parámetros de solicitud (prioridad más alta)

En entornos de alojamiento de plataformas (como ModelScope u otras plataformas MCP), puedes proporcionar una configuración independiente para cada solicitud mediante el objeto meta.auth en los parámetros de la solicitud:

{
  "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"
      }
    }
  }
}

Este método permite el uso multiinquilino, donde cada solicitud puede usar diferentes claves de API y configuraciones.

2. Configuración de la API

Cuando se usa como módulo en otros proyectos, puedes pasar la configuración mediante la función 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. Argumentos de línea de comandos

1. Instala la herramienta CLI globalmente:

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

2. Cuando se usa como herramienta CLI, puedes proporcionar la configuración mediante argumentos de línea de comandos:

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

4. Variables de entorno (prioridad más baja)

El método de configuración más básico es mediante variables de entorno:

# 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

Prioridad de configuración

Cuando se usan múltiples métodos de configuración, se aplica el siguiente orden de prioridad (de mayor a menor):

1. Configuración a nivel de solicitud (mediante meta.auth en cada solicitud de API)
2. Argumentos de línea de comandos
3. Variables de entorno
4. Archivo de configuración
5. Valores predeterminados

Esta priorización garantiza flexibilidad en diferentes escenarios de implementación, manteniendo la capacidad de configuración por solicitud para entornos multiinquilino.

Parámetros de configuración

Parámetro	Descripción	Valor predeterminado
apiKey	Clave de API de MiniMax	Ninguno (obligatorio)
apiHost	Host de API de MiniMax	Host global - https://api.minimaxi.chat, Host de China continental - https://api.minimax.chat
basePath	Ruta base para archivos de salida	Escritorio del usuario
resourceMode	Modo de manejo de recursos, 'url' o 'local'	url

⚠️ Nota: La clave de API debe coincidir con la dirección del host. Se usan hosts diferentes para las versiones global y de China continental:

• Host global: https://api.minimaxi.chat (nota la "i" adicional)
• Host de China continental: https://api.minimax.chat

Ejemplo de uso

⚠️ Advertencia: El uso de estas herramientas puede generar costos.

1. transmitir un segmento de las noticias de la noche

2. clonar una voz

3. generar un video

4. generar imágenes

5. diseño de voz

Herramientas disponibles

Texto a audio

Convierte texto en un archivo de audio de voz.

Nombre de la herramienta: text_to_audio

Parámetros:

• text: Texto a convertir (obligatorio)
• model: Versión del modelo, opciones: 'speech-02-hd', 'speech-02-turbo', 'speech-01-hd', 'speech-01-turbo', 'speech-01-240228', 'speech-01-turbo-240228', el valor predeterminado es 'speech-02-hd'
• voiceId: ID de voz, el valor predeterminado es 'male-qn-qingse'
• speed: Velocidad del habla, rango 0.5-2.0, el valor predeterminado es 1.0
• vol: Volumen, rango 0.1-10.0, el valor predeterminado es 1.0
• pitch: Tono, rango -12 a 12, el valor predeterminado es 0
• emotion: Emoción, opciones: 'happy', 'sad', 'angry', 'fearful', 'disgusted', 'surprised', 'neutral', el valor predeterminado es 'happy'. Nota: Este parámetro solo funciona con los modelos 'speech-02-hd', 'speech-02-turbo', 'speech-01-turbo', 'speech-01-hd'
• format: Formato de audio, opciones: 'mp3', 'pcm', 'flac', 'wav', el valor predeterminado es 'mp3'
• sampleRate: Frecuencia de muestreo (Hz), opciones: 8000, 16000, 22050, 24000, 32000, 44100, el valor predeterminado es 32000
• bitrate: Tasa de bits (bps), opciones: 64000, 96000, 128000, 160000, 192000, 224000, 256000, 320000, el valor predeterminado es 128000
• channel: Canales de audio, opciones: 1 o 2, el valor predeterminado es 1
• languageBoost: Mejora la capacidad de reconocer idiomas y dialectos específicos. Los valores admitidos incluyen: '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', el valor predeterminado es 'auto'
• stream: Habilita la salida en streaming
• subtitleEnable: El parámetro controla si el servicio de subtítulos está habilitado. El modelo debe ser 'speech-01-turbo' o 'speech-01-hd'. Si no se proporciona este parámetro, el valor predeterminado es false
• outputDirectory: Directorio para guardar el archivo de salida. outputDirectory es relativo a MINIMAX_MCP_BASE_PATH (o basePath en la configuración). La ruta final de guardado es ${basePath}/${outputDirectory}. Por ejemplo, si MINIMAX_MCP_BASE_PATH=~/Desktop y outputDirectory=workspace, la salida se guardará en ~/Desktop/workspace/. (opcional)
• outputFile: Ruta para guardar el archivo de salida (opcional, se genera automáticamente si no se proporciona)

Reproducir audio

Reproduce un archivo de audio. Admite formatos WAV y MP3. No admite video.

Nombre de la herramienta: play_audio

Parámetros:

• inputFilePath: Ruta del archivo de audio a reproducir (obligatorio)
• isUrl: Si el archivo de audio es una URL, el valor predeterminado es false

Clonación de voz

Clona una voz a partir de un archivo de audio.

Nombre de la herramienta: voice_clone

Parámetros:

• audioFile: Ruta del archivo de audio (obligatorio)
• voiceId: ID de voz (obligatorio)
• text: Texto para el audio de demostración (opcional)
• outputDirectory: Directorio para guardar el archivo de salida. outputDirectory es relativo a MINIMAX_MCP_BASE_PATH (o basePath en la configuración). La ruta final de guardado es ${basePath}/${outputDirectory}. Por ejemplo, si MINIMAX_MCP_BASE_PATH=~/Desktop y outputDirectory=workspace, la salida se guardará en ~/Desktop/workspace/. (opcional)

Texto a imagen

Genera imágenes a partir de indicaciones de texto.

Nombre de la herramienta: text_to_image

Parámetros:

• prompt: Descripción de la imagen (obligatorio)
• model: Versión del modelo, el valor predeterminado es 'image-01'
• aspectRatio: Relación de aspecto, el valor predeterminado es '1:1', opciones: '1:1', '16:9','4:3', '3:2', '2:3', '3:4', '9:16', '21:9'
• n: Número de imágenes a generar, rango 1-9, el valor predeterminado es 1
• promptOptimizer: Si se optimiza la indicación, el valor predeterminado es true
• subjectReference: Ruta de archivo de imagen local o URL pública para referencia de personaje (opcional)
• outputDirectory: Directorio para guardar el archivo de salida. outputDirectory es relativo a MINIMAX_MCP_BASE_PATH (o basePath en la configuración). La ruta final de guardado es ${basePath}/${outputDirectory}. Por ejemplo, si MINIMAX_MCP_BASE_PATH=~/Desktop y outputDirectory=workspace, la salida se guardará en ~/Desktop/workspace/. (opcional)
• outputFile: Ruta para guardar el archivo de salida (opcional, se genera automáticamente si no se proporciona)
• asyncMode: Si se usa el modo asíncrono. El valor predeterminado es False. Si es True, la tarea de generación de video se enviará de forma asíncrona y la respuesta devolverá un task_id. Se debe usar la herramienta query_video_generation para verificar el estado de la tarea y obtener el resultado. (opcional)

Generar video

Genera videos a partir de indicaciones de texto.

Nombre de la herramienta: generate_video Parámetros:

• prompt: Descripción del video (obligatorio)
• model: Versión del modelo, las opciones son 'T2V-01', 'T2V-01-Director', 'I2V-01', 'I2V-01-Director', 'I2V-01-live', 'S2V-01', 'MiniMax-Hailuo-02', el valor predeterminado es 'MiniMax-Hailuo-02'
• firstFrameImage: Ruta a la imagen del primer fotograma (opcional)
• duration: La duración del video. El modelo debe ser "MiniMax-Hailuo-02". Los valores pueden ser 6 y 10. (opcional)
• resolution: La resolución del video. El modelo debe ser "MiniMax-Hailuo-02". Los valores van desde ["768P", "1080P"]. (opcional)
• outputDirectory: Directorio para guardar el archivo de salida. outputDirectory es relativo a MINIMAX_MCP_BASE_PATH (o basePath en la configuración). La ruta final de guardado es ${basePath}/${outputDirectory}. Por ejemplo, si MINIMAX_MCP_BASE_PATH=~/Desktop y outputDirectory=workspace, la salida se guardará en ~/Desktop/workspace/. (opcional)
• outputFile: Ruta para guardar el archivo de salida (opcional, se genera automáticamente si no se proporciona)
• asyncMode: Si se debe usar el modo asíncrono. El valor predeterminado es False. Si es True, la tarea de generación de video se enviará de forma asíncrona y la respuesta devolverá un task_id. Se debe usar la herramienta query_video_generation para verificar el estado de la tarea y obtener el resultado. (opcional)

Consultar el estado de generación de video

Consulta el estado de una tarea de generación de video.

Nombre de la herramienta: query_video_generation

Parámetros:

• taskId: El ID de la tarea a consultar. Debe ser el task_id devuelto por la herramienta generate_video si async_mode es True. (obligatorio)
• outputDirectory: Directorio para guardar el archivo de salida. outputDirectory es relativo a MINIMAX_MCP_BASE_PATH (o basePath en la configuración). La ruta final de guardado es ${basePath}/${outputDirectory}. Por ejemplo, si MINIMAX_MCP_BASE_PATH=~/Desktop y outputDirectory=workspace, la salida se guardará en ~/Desktop/workspace/. (opcional)

Diseño de voz

Genera una voz basada en indicaciones de descripción.

Nombre de la herramienta: voice_design

Parámetros:

• prompt: La indicación para generar la voz. (obligatorio)
• previewText: El texto para previsualizar la voz. (obligatorio)
• voiceId: El id de la voz a utilizar. Por ejemplo, "male-qn-qingse"/"audiobook_female_1"/"cute_boy"/"Charming_Lady"... (opcional)
• outputDirectory: El directorio para guardar el archivo de salida. outputDirectory es relativo a MINIMAX_MCP_BASE_PATH (o basePath en la configuración). La ruta final de guardado es ${basePath}/${outputDirectory}. Por ejemplo, si MINIMAX_MCP_BASE_PATH=~/Desktop y outputDirectory=workspace, la salida se guardará en ~/Desktop/workspace/. (opcional)

Preguntas frecuentes

1. Cómo usar generate_video en modo asíncrono

Defina las reglas de finalización antes de comenzar: Alternativamente, estas reglas se pueden configurar en la configuración de su IDE (por ejemplo, Cursor):

Desarrollo

Configuración

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

# Install dependencies
pnpm install

Compilación

# Build the project
pnpm run build

Ejecución

# Run the MCP server
pnpm start

Licencia

MIT