MiniMax MCP JS

Documentação

• Documentação em chinês
• Versão Python - Implementação oficial em Python do MiniMax MCP

Notas de versão

22 de julho de 2025

🔧 Correções e melhorias

• Correções na ferramenta TTS: Corrigido o tratamento de parâmetros para languageBoost e subtitleEnable na ferramenta text_to_audio
• Melhoria na resposta da API: A API TTS pode retornar tanto o arquivo de áudio quanto o arquivo de legenda, proporcionando uma experiência mais completa de fala para texto

7 de julho de 2025

🆕 Novidades

• Design de voz: Nova ferramenta voice_design - crie vozes personalizadas a partir de descrições textuais com áudio de pré-visualização
• Aprimoramento de vídeo: Adicionado o modelo MiniMax-Hailuo-02 com qualidade ultra nítida e controles de duração/resolução

📈 Ferramentas aprimoradas

• voice_design - Gere vozes personalizadas a partir de descrições textuais
• generate_video - Agora suporta MiniMax-Hailuo-02 com opções de duração de 6s/10s e resolução de 768P/1080P

Recursos

• Conversão de texto em fala (TTS)
• Geração de imagens
• Geração de vídeos
• Clonagem de voz
• Design de voz
• Configuração dinâmica (suporta variáveis de ambiente e parâmetros de requisição)
• Compatível com hospedagem em plataformas MCP (ModelScope e outras plataformas MCP)

Instalação

Instalação via Smithery

Para instalar o MiniMax MCP JS para Claude Desktop automaticamente via Smithery:

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

Instalação manual

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

Início rápido

O MiniMax MCP JS implementa a especificação do Model Context Protocol (MCP) e pode ser usado como servidor para interagir com clientes compatíveis com MCP (como Claude AI).

Início rápido com cliente MCP

1. Obtenha sua chave de API na Plataforma Internacional MiniMax.
2. Certifique-se de que você já instalou o Node.js e npm
3. Importante: API HOST e KEY são diferentes em cada região, eles devem corresponder, caso contrário você receberá um erro Invalid API key.

Região	Global	China continental
MINIMAX_API_KEY	obter em MiniMax Global	obter em MiniMax
MINIMAX_API_HOST	​https://api.minimaxi.chat (observe o "i" extra)	​https://api.minimax.chat

Uso com clientes MCP (recomendado)

Configure seu cliente MCP:

Claude Desktop

Vá para 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

Vá para Cursor → Preferences → Cursor Settings → MCP → Add new global MCP Server para adicionar a configuração acima.

⚠️ Nota: Se você encontrar um erro de "Nenhuma ferramenta encontrada" ao usar o MiniMax MCP JS com o Cursor, atualize seu Cursor para a versão mais recente. Para mais informações, consulte este tópico de discussão.

Pronto. Seu cliente MCP agora pode interagir com o MiniMax por meio dessas ferramentas.

Para desenvolvimento local: Ao desenvolver localmente, você pode usar npm link para testar suas alterações:

# In your project directory
npm link

Em seguida, configure o Claude Desktop ou o Cursor para usar npx conforme mostrado acima. Isso usará automaticamente sua versão vinculada.

⚠️ Nota: A chave de API precisa corresponder ao endereço do host. Hosts diferentes são usados para as versões global e China continental:

• Host Global: https://api.minimaxi.chat (observe o "i" extra)
• Host China continental: https://api.minimaxi.chat

Modos de transporte

O MiniMax MCP JS suporta três modos de transporte:

Recurso	stdio (padrão)	REST	SSE
Ambiente	Somente local	Local ou implantação em nuvem	Local ou implantação em nuvem
Comunicação	Via standard I/O	Via HTTP requests	Via server-sent events
Casos de uso	Integração com cliente MCP local	Serviços de API, chamadas entre linguagens	Aplicações que exigem push do servidor
Restrições de entrada	Suporta recursos local files ou URL	Quando implantado em nuvem, entrada URL recomendada	Quando implantado em nuvem, entrada URL recomendada

Configuração

O MiniMax-MCP-JS fornece múltiplos métodos flexíveis de configuração para se adaptar a diferentes casos de uso. A prioridade de configuração, da mais alta para a mais baixa, é a seguinte:

1. Configuração por parâmetro de requisição (prioridade mais alta)

Em ambientes de hospedagem em plataforma (como ModelScope ou outras plataformas MCP), você pode fornecer uma configuração independente para cada requisição por meio do objeto meta.auth nos parâmetros da requisição:

{
  "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 uso multi-tenant, onde cada requisição pode usar diferentes chaves de API e configurações.

2. Configuração da API

Quando usado como módulo em outros projetos, você pode passar a configuração por meio da função 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 linha de comando

1. Instale a ferramenta CLI globalmente:

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

2. Quando usado como ferramenta CLI, você pode fornecer configuração por meio de argumentos de linha de comando:

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

4. Variáveis de ambiente (prioridade mais baixa)

O método de configuração mais básico é por meio de variáveis de ambiente:

# 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

Prioridade de configuração

Quando múltiplos métodos de configuração são usados, a seguinte ordem de prioridade se aplica (da mais alta para a mais baixa):

1. Configuração no nível da requisição (via meta.auth em cada requisição de API)
2. Argumentos de linha de comando
3. Variáveis de ambiente
4. Arquivo de configuração
5. Valores padrão

Essa priorização garante flexibilidade em diferentes cenários de implantação, mantendo a capacidade de configuração por requisição para ambientes multi-tenant.

Parâmetros de configuração

Parâmetro	Descrição	Valor padrão
apiKey	Chave da API MiniMax	Nenhum (obrigatório)
apiHost	Host da API MiniMax	Host Global - https://api.minimaxi.chat, Host China continental - https://api.minimax.chat
basePath	Caminho base para arquivos de saída	Área de trabalho do usuário
resourceMode	Modo de tratamento de recursos, 'url' ou 'local'	url

⚠️ Nota: A chave de API precisa corresponder ao endereço do host. Hosts diferentes são usados para as versões global e China continental:

• Host Global: https://api.minimaxi.chat (observe o "i" extra)
• Host China continental: https://api.minimax.chat

Exemplo de uso

⚠️ Aviso: O uso dessas ferramentas pode gerar custos.

1. transmitir um trecho do noticiário noturno

2. clonar uma voz

3. gerar um vídeo

4. gerar imagens

5. design de voz

Ferramentas disponíveis

Texto para áudio

Converte texto em arquivo de áudio de fala.

Nome da ferramenta: text_to_audio

Parâmetros:

• text: Texto a ser convertido (obrigatório)
• model: Versão do modelo, opções: 'speech-02-hd', 'speech-02-turbo', 'speech-01-hd', 'speech-01-turbo', 'speech-01-240228', 'speech-01-turbo-240228', padrão é 'speech-02-hd'
• voiceId: ID da voz, padrão é 'male-qn-qingse'
• speed: Velocidade da fala, intervalo 0,5-2,0, padrão é 1,0
• vol: Volume, intervalo 0,1-10,0, padrão é 1,0
• pitch: Tom, intervalo -12 a 12, padrão é 0
• emotion: Emoção, opções: 'happy', 'sad', 'angry', 'fearful', 'disgusted', 'surprised', 'neutral', padrão é 'happy'. Nota: Este parâmetro funciona apenas com os modelos 'speech-02-hd', 'speech-02-turbo', 'speech-01-turbo', 'speech-01-hd'
• format: Formato de áudio, opções: 'mp3', 'pcm', 'flac', 'wav', padrão é 'mp3'
• sampleRate: Taxa de amostragem (Hz), opções: 8000, 16000, 22050, 24000, 32000, 44100, padrão é 32000
• bitrate: Taxa de bits (bps), opções: 64000, 96000, 128000, 160000, 192000, 224000, 256000, 320000, padrão é 128000
• channel: Canais de áudio, opções: 1 ou 2, padrão é 1
• languageBoost: Aprimora a capacidade de reconhecer idiomas e dialetos especificados. Valores suportados incluem: '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', padrão é 'auto'
• stream: Ativa a saída em streaming
• subtitleEnable: O parâmetro controla se o serviço de legendas está ativado. O modelo deve ser 'speech-01-turbo' ou 'speech-01-hd'. Se este parâmetro não for fornecido, o valor padrão é false
• outputDirectory: Diretório para salvar o arquivo de saída. outputDirectory é relativo a MINIMAX_MCP_BASE_PATH (ou basePath na configuração). O caminho final de salvamento é ${basePath}/${outputDirectory}. Por exemplo, se MINIMAX_MCP_BASE_PATH=~/Desktop e outputDirectory=workspace, a saída será salva em ~/Desktop/workspace/. (opcional)
• outputFile: Caminho para salvar o arquivo de saída (opcional, gerado automaticamente se não fornecido)

Reproduzir áudio

Reproduz um arquivo de áudio. Suporta formatos WAV e MP3. Não suporta vídeo.

Nome da ferramenta: play_audio

Parâmetros:

• inputFilePath: Caminho para o arquivo de áudio a ser reproduzido (obrigatório)
• isUrl: Se o arquivo de áudio é uma URL, padrão é false

Clonagem de voz

Clona uma voz a partir de um arquivo de áudio.

Nome da ferramenta: voice_clone

Parâmetros:

• audioFile: Caminho para o arquivo de áudio (obrigatório)
• voiceId: ID da voz (obrigatório)
• text: Texto para áudio de demonstração (opcional)
• outputDirectory: Diretório para salvar o arquivo de saída. outputDirectory é relativo a MINIMAX_MCP_BASE_PATH (ou basePath na configuração). O caminho final de salvamento é ${basePath}/${outputDirectory}. Por exemplo, se MINIMAX_MCP_BASE_PATH=~/Desktop e outputDirectory=workspace, a saída será salva em ~/Desktop/workspace/. (opcional)

Texto para imagem

Gera imagens com base em descrições textuais.

Nome da ferramenta: text_to_image

Parâmetros:

• prompt: Descrição da imagem (obrigatório)
• model: Versão do modelo, padrão é 'image-01'
• aspectRatio: Proporção de aspecto, padrão é '1:1', opções: '1:1', '16:9','4:3', '3:2', '2:3', '3:4', '9:16', '21:9'
• n: Número de imagens a gerar, intervalo 1-9, padrão é 1
• promptOptimizer: Se deve otimizar o prompt, padrão é true
• subjectReference: Caminho para arquivo de imagem local ou URL pública para referência de personagem (opcional)
• outputDirectory: Diretório para salvar o arquivo de saída. outputDirectory é relativo a MINIMAX_MCP_BASE_PATH (ou basePath na configuração). O caminho final de salvamento é ${basePath}/${outputDirectory}. Por exemplo, se MINIMAX_MCP_BASE_PATH=~/Desktop e outputDirectory=workspace, a saída será salva em ~/Desktop/workspace/. (opcional)
• outputFile: Caminho para salvar o arquivo de saída (opcional, gerado automaticamente se não fornecido)
• asyncMode: Se deve usar modo assíncrono. O padrão é False. Se True, a tarefa de geração de vídeo será enviada de forma assíncrona e a resposta retornará um task_id. Deve-se usar a ferramenta query_video_generation para verificar o status da tarefa e obter o resultado. (opcional)

Gerar vídeo

Gera vídeos com base em descrições textuais.

Nome da ferramenta: generate_video Parâmetros:

• prompt: Descrição do vídeo (obrigatório)
• model: Versão do modelo, as opções são 'T2V-01', 'T2V-01-Director', 'I2V-01', 'I2V-01-Director', 'I2V-01-live', 'S2V-01', 'MiniMax-Hailuo-02', o padrão é 'MiniMax-Hailuo-02'
• firstFrameImage: Caminho para a imagem do primeiro quadro (opcional)
• duration: A duração do vídeo. O modelo deve ser "MiniMax-Hailuo-02". Os valores podem ser 6 e 10. (opcional)
• resolution: A resolução do vídeo. O modelo deve ser "MiniMax-Hailuo-02". Os valores variam entre ["768P", "1080P"]. (opcional)
• outputDirectory: Diretório para salvar o arquivo de saída. outputDirectory é relativo a MINIMAX_MCP_BASE_PATH (ou basePath na configuração). O caminho final de salvamento é ${basePath}/${outputDirectory}. Por exemplo, se MINIMAX_MCP_BASE_PATH=~/Desktop e outputDirectory=workspace, a saída será salva em ~/Desktop/workspace/. (opcional)
• outputFile: Caminho para salvar o arquivo de saída (opcional, gerado automaticamente se não for fornecido)
• asyncMode: Se deve usar o modo assíncrono. O padrão é False. Se True, a tarefa de geração de vídeo será enviada de forma assíncrona e a resposta retornará um task_id. Deve-se usar a ferramenta query_video_generation para verificar o status da tarefa e obter o resultado. (opcional)

Consultar o Status da Geração de Vídeo

Consulte o status de uma tarefa de geração de vídeo.

Nome da Ferramenta: query_video_generation

Parâmetros:

• taskId: O ID da tarefa a ser consultado. Deve ser o task_id retornado pela ferramenta generate_video se async_mode for True. (obrigatório)
• outputDirectory: Diretório para salvar o arquivo de saída. outputDirectory é relativo a MINIMAX_MCP_BASE_PATH (ou basePath na configuração). O caminho final de salvamento é ${basePath}/${outputDirectory}. Por exemplo, se MINIMAX_MCP_BASE_PATH=~/Desktop e outputDirectory=workspace, a saída será salva em ~/Desktop/workspace/. (opcional)

Design de Voz

Gere uma voz com base em prompts de descrição.

Nome da Ferramenta: voice_design

Parâmetros:

• prompt: O prompt para gerar a voz. (obrigatório)
• previewText: O texto para pré-visualizar a voz. (obrigatório)
• voiceId: O id da voz a ser usada. Por exemplo, "male-qn-qingse"/"audiobook_female_1"/"cute_boy"/"Charming_Lady"... (opcional)
• outputDirectory: O diretório para salvar o arquivo de saída. outputDirectory é relativo a MINIMAX_MCP_BASE_PATH (ou basePath na configuração). O caminho final de salvamento é ${basePath}/${outputDirectory}. Por exemplo, se MINIMAX_MCP_BASE_PATH=~/Desktop e outputDirectory=workspace, a saída será salva em ~/Desktop/workspace/. (opcional)

FAQ

1. Como usar generate_video no modo assíncrono

Defina as regras de conclusão antes de começar: Alternativamente, essas regras podem ser configuradas nas configurações do seu IDE (por exemplo, Cursor):

Desenvolvimento

Configuração

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

# Install dependencies
pnpm install

Build

# Build the project
pnpm run build

Executar

# Run the MCP server
pnpm start

Licença

MIT