MiniMax MCP JS

Instructions

Implementation Reference

• src/api/tts.ts:16-111 (handler)

  Core handler function that implements text-to-audio conversion by calling MiniMax TTS API endpoint /v1/t2a_v2, validates parameters, prepares request payload, handles response (hex to binary conversion, file saving or URL return), includes helper validators for parameters.
  async generateSpeech(request: TTSRequest): Promise<any> { // Validate required parameters if (!request.text || request.text.trim() === '') { throw new MinimaxRequestError(ERROR_TEXT_REQUIRED); } // Process output file let outputFile = request.outputFile; if (!outputFile) { // If no output file is provided, generate one based on text content const textPrefix = request.text.substring(0, 20).replace(/[^\w]/g, '_'); outputFile = `tts_${textPrefix}_${Date.now()}`; } if (!path.extname(outputFile)) { // If no extension, add one based on format const format = request.format || 'mp3'; outputFile = buildOutputFile(outputFile, request.outputDirectory, format); } // Prepare request data according to MiniMax API nested structure const requestData: Record<string, any> = { model: this.ensureValidModel(request.model), text: request.text, voice_setting: { voice_id: request.voiceId || 'male-qn-qingse', speed: request.speed || 1.0, vol: request.vol || 1.0, pitch: request.pitch || 0, emotion: this.ensureValidEmotion(request.emotion, this.ensureValidModel(request.model)) }, audio_setting: { sample_rate: this.ensureValidSampleRate(request.sampleRate), bitrate: this.ensureValidBitrate(request.bitrate), format: this.ensureValidFormat(request.format), channel: this.ensureValidChannel(request.channel) }, language_boost: request.languageBoost || 'auto', stream: request.stream, subtitle_enable: request.subtitleEnable }; // Add output format (if specified) if (request.outputFormat === RESOURCE_MODE_URL) { requestData.output_format = 'url'; } // Filter out undefined fields (recursive) const filteredData = this.removeUndefinedFields(requestData); try { // Send request const response = await this.api.post<any>('/v1/t2a_v2', filteredData); // Process response const audioData = response?.data?.audio; const subtitleFile = response?.data?.subtitle_file; if (!audioData) { throw new MinimaxRequestError('Could not get audio data from response'); } // If URL mode, return URL directly if (request.outputFormat === RESOURCE_MODE_URL) { return { audio: audioData, subtitle: subtitleFile }; } // If base64 mode, decode and save file try { // Convert hex string to binary const audioBuffer = Buffer.from(audioData, 'hex'); // Ensure output directory exists const outputDir = path.dirname(outputFile); if (!fs.existsSync(outputDir)) { fs.mkdirSync(outputDir, { recursive: true }); } // Write to file fs.writeFileSync(outputFile, audioBuffer); return { audio: outputFile, subtitle: subtitleFile }; } catch (error) { throw new MinimaxRequestError(`Failed to save audio file: ${String(error)}`); } } catch (error) { throw error; } }
• src/mcp-server.ts:123-256 (registration)

  Tool registration using McpServer.tool() with name 'text_to_audio', detailed description, Zod input schema defining all parameters with descriptions/defaults/validations, and async handler that prepares params and calls TTSAPI.generateSpeech
  private registerTextToAudioTool(): void { this.server.tool( 'text_to_audio', 'Convert text to audio with a given voice and save the output audio file to a given directory. If no directory is provided, the file will be saved to desktop. If no voice ID is provided, the default voice will be used.\n\nNote: This tool calls MiniMax API and may incur costs. Use only when explicitly requested by the user.', { text: z.string().describe('Text to convert to audio'), outputDirectory: COMMON_PARAMETERS_SCHEMA.outputDirectory, voiceId: z.string().optional().default(DEFAULT_VOICE_ID).describe('Voice ID to use, e.g. "female-shaonv"'), model: z.string().optional().default(DEFAULT_SPEECH_MODEL).describe('Model to use'), speed: z.number().min(0.5).max(2.0).optional().default(DEFAULT_SPEED).describe('Speech speed'), vol: z.number().min(0.1).max(10.0).optional().default(DEFAULT_VOLUME).describe('Speech volume'), pitch: z.number().min(-12).max(12).optional().default(DEFAULT_PITCH).describe('Speech pitch'), emotion: z .string() .optional() .default(DEFAULT_EMOTION) .describe('Speech emotion, values: ["happy", "sad", "angry", "fearful", "disgusted", "surprised", "neutral"]'), format: z .string() .optional() .default(DEFAULT_FORMAT) .describe('Audio format, values: ["pcm", "mp3","flac", "wav"]'), sampleRate: z .number() .optional() .default(DEFAULT_SAMPLE_RATE) .describe('Sample rate (Hz), values: [8000, 16000, 22050, 24000, 32000, 44100]'), bitrate: z .number() .optional() .default(DEFAULT_BITRATE) .describe('Bitrate (bps), values: [64000, 96000, 128000, 160000, 192000, 224000, 256000, 320000]'), channel: z.number().optional().default(DEFAULT_CHANNEL).describe('Audio channels, values: [1, 2]'), languageBoost: z.string().optional().default(DEFAULT_LANGUAGE_BOOST) .describe(`Enhance the ability to recognize specified languages and dialects. Supported values include: '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', default is 'auto'`), subtitleEnable: z .boolean() .optional() .default(false) .describe( `The parameter controls whether the subtitle service is enabled. The model must be 'speech-01-turbo' or 'speech-01-hd'. If this parameter is not provided, the default value is false`, ), outputFile: z .string() .optional() .describe('Path to save the generated audio file, automatically generated if not provided'), }, async (args, extra) => { try { // Build TTS request parameters const ttsParams = { text: args.text, outputDirectory: args.outputDirectory, voiceId: args.voiceId || DEFAULT_VOICE_ID, model: args.model || DEFAULT_SPEECH_MODEL, speed: args.speed || DEFAULT_SPEED, vol: args.vol || DEFAULT_VOLUME, pitch: args.pitch || DEFAULT_PITCH, emotion: args.emotion || DEFAULT_EMOTION, format: args.format || DEFAULT_FORMAT, sampleRate: args.sampleRate || DEFAULT_SAMPLE_RATE, bitrate: args.bitrate || DEFAULT_BITRATE, channel: args.channel || DEFAULT_CHANNEL, languageBoost: args.languageBoost || DEFAULT_LANGUAGE_BOOST, subtitleEnable: args.subtitleEnable || false, outputFile: args.outputFile, }; // Use global configuration const requestApiKey = this.config.apiKey; if (!requestApiKey) { throw new Error(ERROR_API_KEY_REQUIRED); } // Update configuration with request-specific parameters const requestConfig: Partial<Config> = { apiKey: requestApiKey, apiHost: this.config.apiHost, resourceMode: this.config.resourceMode, }; // Update API instance const requestApi = new MiniMaxAPI(requestConfig as Config); const requestTtsApi = new TTSAPI(requestApi); // Automatically set resource mode (if not specified) const outputFormat = requestConfig.resourceMode; const ttsRequest = { ...ttsParams, outputFormat, }; // If no output filename is provided, generate one automatically if (!ttsRequest.outputFile) { const textPrefix = ttsRequest.text.substring(0, 20).replace(/[^\w]/g, '_'); ttsRequest.outputFile = `tts_${textPrefix}_${Date.now()}`; } const result = await requestTtsApi.generateSpeech(ttsRequest); // Return different messages based on output format if (outputFormat === RESOURCE_MODE_URL) { return { content: [ { type: 'text', text: `Success. Audio URL: ${result.audio}. ${ttsParams.subtitleEnable ? `Subtitle file saved: ${result.subtitle}` : ''}`, }, ], }; } else { return { content: [ { type: 'text', text: `Audio file saved: ${result.audio}. ${ttsParams.subtitleEnable ? `Subtitle file saved: ${result.subtitle}. ` : ''}Voice used: ${ttsParams.voiceId}`, }, ], }; } } catch (error) { return { content: [ { type: 'text', text: `Failed to generate audio: ${error instanceof Error ? error.message : String(error)}`, }, ], }; } }, ); }
• src/mcp-rest-server.ts:204-245 (schema)

  JSON schema definition for text_to_audio tool used in REST server's list tools handler, includes all input parameters with types and descriptions.
  { name: 'text_to_audio', description: 'Convert text to audio', arguments: [ { name: 'text', description: 'Text to convert to audio', required: true }, { name: 'outputDirectory', description: OUTPUT_DIRECTORY_DESCRIPTION, required: false }, { name: 'voiceId', description: 'Voice ID to use, e.g. "female-shaonv"', required: false }, { name: 'model', description: 'Model to use', required: false }, { name: 'speed', description: 'Speech speed (0.5-2.0)', required: false }, { name: 'vol', description: 'Speech volume (0.1-10.0)', required: false }, { name: 'pitch', description: 'Speech pitch (-12 to 12)', required: false }, { name: 'emotion', description: 'Speech emotion, values: ["happy", "sad", "angry", "fearful", "disgusted", "surprised", "neutral"]', required: false }, { name: 'format', description: 'Audio format, values: ["pcm", "mp3","flac", "wav"]', required: false }, { name: 'sampleRate', description: 'Sample rate (Hz), values: [8000, 16000, 22050, 24000, 32000, 44100]', required: false }, { name: 'bitrate', description: 'Bitrate (bps), values: [64000, 96000, 128000, 160000, 192000, 224000, 256000, 320000]', required: false }, { name: 'channel', description: 'Audio channels, values: [1, 2]', required: false }, { name: 'languageBoost', description: `Enhance the ability to recognize specified languages and dialects. Supported values include: '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', default is 'auto'`, required: false }, { name: 'subtitleEnable', description: `The parameter controls whether the subtitle service is enabled. The model must be 'speech-01-turbo' or 'speech-01-hd'. If this parameter is not provided, the default value is false`, required: false }, { name: 'outputFile', description: 'Output file path, auto-generated if not provided', required: false } ], inputSchema: { type: 'object', properties: { text: { type: 'string' }, outputDirectory: { type: 'string' }, voiceId: { type: 'string' }, model: { type: 'string' }, speed: { type: 'number' }, vol: { type: 'number' }, pitch: { type: 'number' }, emotion: { type: 'string' }, format: { type: 'string' }, sampleRate: { type: 'number' }, bitrate: { type: 'number' }, channel: { type: 'number' }, languageBoost: { type: 'string' }, subtitleEnable: { type: 'boolean' }, outputFile: { type: 'string' } }, required: ['text'] } },
• src/mcp-rest-server.ts:256-489 (handler)

  Handler wrapper in REST server that dispatches to mediaService.generateSpeech with retry logic.
  }, required: ['voiceType'] } }, { name: 'play_audio', description: 'Play audio file. Supports WAV and MP3 formats. Does not support video.', arguments: [ { name: 'inputFilePath', description: 'Path to audio file to play', required: true }, { name: 'isUrl', description: 'Whether audio file is a URL', required: false } ], inputSchema: { type: 'object', properties: { inputFilePath: { type: 'string' }, isUrl: { type: 'boolean' } }, required: ['inputFilePath'] } }, { name: 'text_to_image', description: 'Generate image based on text prompt', arguments: [ { name: 'prompt', description: 'Text prompt for image generation', required: true }, { name: 'model', description: 'Model to use', required: false }, { name: 'aspectRatio', description: 'Image aspect ratio, values: ["1:1", "16:9","4:3", "3:2", "2:3", "3:4", "9:16", "21:9"]', required: false }, { name: 'n', description: 'Number of images to generate (1-9)', required: false }, { name: 'promptOptimizer', description: 'Whether to optimize prompt', required: false }, { name: 'outputDirectory', description: OUTPUT_DIRECTORY_DESCRIPTION, required: false }, { name: 'outputFile', description: 'Output file path, auto-generated if not provided', required: false } ], inputSchema: { type: 'object', properties: { prompt: { type: 'string' }, model: { type: 'string' }, aspectRatio: { type: 'string' }, n: { type: 'number' }, promptOptimizer: { type: 'boolean' }, outputDirectory: { type: 'string' }, outputFile: { type: 'string' } }, required: ['prompt'] } }, { name: 'generate_video', description: 'Generate video based on text prompt', arguments: [ { name: 'prompt', description: 'Text prompt for video generation', required: true }, { name: 'model', description: 'Model to use, values: ["T2V-01", "T2V-01-Director", "I2V-01", "I2V-01-Director", "I2V-01-live", "MiniMax-Hailuo-02"]', required: false }, { name: 'firstFrameImage', description: 'First frame image', required: false }, { name: 'outputDirectory', description: OUTPUT_DIRECTORY_DESCRIPTION, required: false }, { name: 'outputFile', description: 'Output file path, auto-generated if not provided', required: false }, { name: 'async_mode', description: 'Whether to use async mode. Defaults to False. If True, the video generation task will be submitted asynchronously and the response will return a task_id. Should use `query_video_generation` tool to check the status of the task and get the result', required: false }, { name: 'resolution', description: 'The resolution of the video. The model must be "MiniMax-Hailuo-02". Values range ["768P", "1080P"]', required: false }, { name: 'duration', description: 'The duration of the video. The model must be "MiniMax-Hailuo-02". Values can be 6 and 10.', required: false }, ], inputSchema: { type: 'object', properties: { prompt: { type: 'string' }, model: { type: 'string' }, firstFrameImage: { type: 'string' }, outputDirectory: { type: 'string' }, outputFile: { type: 'string' }, async_mode: { type: 'boolean' }, resolution: { type: 'string' }, duration: { type: 'number' } }, required: ['prompt'] } }, { name: 'voice_clone', description: 'Clone voice using provided audio file', arguments: [ { name: 'voiceId', description: 'Voice ID to use', required: true }, { name: 'audioFile', description: 'Audio file path', required: true }, { name: 'text', description: 'Text for demo audio', required: false }, { name: 'outputDirectory', description: OUTPUT_DIRECTORY_DESCRIPTION, required: false }, { name: 'isUrl', description: 'Whether audio file is a URL', required: false } ], inputSchema: { type: 'object', properties: { voiceId: { type: 'string' }, audioFile: { type: 'string' }, text: { type: 'string' }, outputDirectory: { type: 'string' }, isUrl: { type: 'boolean' } }, required: ['voiceId', 'audioFile'] } }, { name: 'image_to_video', description: 'Generate video based on image', arguments: [ { name: 'prompt', description: 'Text prompt for video generation', required: true }, { name: 'firstFrameImage', description: 'Path to first frame image', required: true }, { name: 'model', description: 'Model to use, values: ["I2V-01", "I2V-01-Director", "I2V-01-live"]', required: false }, { name: 'outputDirectory', description: OUTPUT_DIRECTORY_DESCRIPTION, required: false }, { name: 'outputFile', description: 'Output file path, auto-generated if not provided', required: false }, { name: 'async_mode', description: 'Whether to use async mode. Defaults to False. If True, the video generation task will be submitted asynchronously and the response will return a task_id. Should use `query_video_generation` tool to check the status of the task and get the result', required: false } ], inputSchema: { type: 'object', properties: { prompt: { type: 'string' }, firstFrameImage: { type: 'string' }, model: { type: 'string' }, outputDirectory: { type: 'string' }, outputFile: { type: 'string' }, async_mode: { type: 'boolean' } }, required: ['prompt', 'firstFrameImage'] } }, { name: 'music_generation', description: 'Generate music based on text prompt and lyrics', arguments: [ { name: 'prompt', description: 'Music creation inspiration describing style, mood, scene, etc.', required: true }, { name: 'lyrics', description: 'Song lyrics for music generation.\nUse newline (\\n) to separate each line of lyrics. Supports lyric structure tags [Intro][Verse][Chorus][Bridge][Outro]\nto enhance musicality. Character range: [10, 600] (each Chinese character, punctuation, and letter counts as 1 character)', required: true }, { name: 'sampleRate', description: 'Sample rate of generated music', required: false }, { name: 'bitrate', description: 'Bitrate of generated music', required: false }, { name: 'format', description: 'Format of generated music', required: false }, { name: 'outputDirectory', description: OUTPUT_DIRECTORY_DESCRIPTION, required: false } ], inputSchema: { type: 'object', properties: { prompt: { type: 'string' }, lyrics: { type: 'string' }, sampleRate: { type: 'number' }, bitrate: { type: 'number' }, format: { type: 'string' }, outputDirectory: { type: 'string' } }, required: ['prompt', 'lyrics'] } }, { name: 'voice_design', description: 'Generate a voice based on description prompts', arguments: [ { name: 'prompt', description: 'The prompt to generate the voice from', required: true }, { name: 'previewText', description: 'The text to preview the voice', required: true }, { name: 'voiceId', description: 'The id of the voice to use', required: false }, { name: 'outputDirectory', description: OUTPUT_DIRECTORY_DESCRIPTION, required: false } ], inputSchema: { type: 'object', properties: { prompt: { type: 'string' }, previewText: { type: 'string' }, voiceId: { type: 'string' }, outputDirectory: { type: 'string' } }, required: ['prompt', 'previewText'] } } ] }; } catch (error) { throw this.wrapError('Failed to get tool list', error); } }); // Call tool handler this.server.setRequestHandler(CallToolRequestSchema, async (request) => { const toolName = request.params.tool; const toolParams = request.params.params || {}; try { // Create configuration and API instance for this request const requestConfig = this.getRequestConfig(request); const requestApi = new MiniMaxAPI(requestConfig); const mediaService = new MediaService(requestApi); // Log API key (partially hidden) const apiKey = this.extractApiKeyFromRequest(request); const maskedKey = apiKey ? `${apiKey.substring(0, 4)}****${apiKey.substring(apiKey.length - 4)}` : 'not provided'; // console.log(`[${new Date().toISOString()}] Using API key: ${maskedKey} to call tool: ${toolName}`); // Choose different handler function based on tool name switch (toolName) { case 'text_to_audio': return await this.handleTextToAudio(toolParams, requestApi, mediaService); case 'list_voices': return await this.handleListVoices(toolParams, requestApi, mediaService); case 'play_audio': return await this.handlePlayAudio(toolParams); case 'text_to_image': return await this.handleTextToImage(toolParams, requestApi, mediaService); case 'generate_video': return await this.handleGenerateVideo(toolParams, requestApi, mediaService); case 'voice_clone': return await this.handleVoiceClone(toolParams, requestApi, mediaService); case 'image_to_video': return await this.handleImageToVideo(toolParams, requestApi, mediaService); case 'query_video_generation': return await this.handleVideoGenerationQuery(toolParams, requestApi, mediaService); case 'music_generation': return await this.handleGenerateMusic(toolParams, requestApi, mediaService); case 'voice_design': return await this.handleVoiceDesign(toolParams, requestApi, mediaService); default: throw new Error(`Unknown tool: ${toolName}`); } } catch (error) { throw this.wrapError(`Failed to call tool ${toolName}`, error); } }); } /** * Handle text to speech request */ private async handleTextToAudio(args: any, api: MiniMaxAPI, mediaService: MediaService, attempt = 1): Promise<any> {
• src/services/media-service.ts:70-78 (handler)

  MediaService wrapper that delegates text-to-audio execution to TTSAPI.generateSpeech.
  public async generateSpeech(params: any): Promise<string> { this.checkInitialized(); try { return await this.ttsApi.generateSpeech(params); } catch (error) { // console.error(`[${new Date().toISOString()}] Failed to generate speech:`, error); throw this.wrapError('Failed to generate speech', error); } }