MiniMax MCP Server

A Model Context Protocol (MCP) server that provides tools for web search, image understanding, text-to-speech, and image generation using the MiniMax API.

Features

• Web Search — Search the web with MiniMax's search API

• Image Understanding — Analyze images from URLs or local files using vision models

• Text-to-Speech — Generate natural speech audio with multiple voice options

• Image Generation — Create images from text descriptions

Related MCP server: MiniMax MCP

Requirements

• Python 3.11+

• MiniMax API key

Installation

Clone the repository

git clone https://github.com/Klng79/minimax-mcp.git
cd minimax-mcp

Install dependencies

pip install -r requirements.txt

Set your API key

Export your MiniMax API key as an environment variable:

export MINIMAX_API_KEY="your_api_key_here"

Or add it to your shell profile (~/.zshrc or ~/.bashrc) for persistence.

Windows Installation

On Windows, the steps are similar but paths and commands differ slightly.

1. Install dependencies

pip install -r requirements.txt

2. Set your API key

Set the MINIMAX_API_KEY environment variable via Command Prompt or PowerShell:

set MINIMAX_API_KEY=your_api_key_here

Or set it permanently via System Properties → Environment Variables.

3. Add to Claude Code

Open %APPDATA%\Claude\settings.json in a text editor and add:

{
  "mcpServers": {
    "minimax": {
      "command": "python",
      "args": ["C:\\path\\to\\minimax-mcp\\minimax_mcp.py"],
      "env": {
        "MINIMAX_API_KEY": "your_api_key_here"
      }
    }
  }
}

Note: Use python instead of python3 on Windows.

4. Restart Claude Code

After updating settings, restart Claude Code to load the new MCP server.

Usage

Claude Code Integration

Add the server to your Claude Code configuration in ~/.claude/settings.json:

{
  "mcpServers": {
    "minimax": {
      "command": "python3",
      "args": ["/path/to/minimax-mcp/minimax_mcp.py"]
    }
  }
}

Make sure MINIMAX_API_KEY is set in your environment before launching Claude Code.

Command Line

You can also use the Python server directly:

python minimax_mcp.py

Hermes Integration (mcporter)

The server works with Hermes's mcporter CLI tool, which auto-discovers configured MCP servers.

Hermes Setup via ~/.claude.json

{
  "mcpServers": {
    "minimax": {
      "command": "python3",
      "args": ["/absolute/path/to/minimax-mcp/minimax_mcp.py"],
      "env": {
        "MINIMAX_API_KEY": "your_api_key_here"
      }
    }
  }
}

Hermes Setup via OpenClaw config

{
  "mcpServers": {
    "minimax": {
      "command": "python3",
      "args": ["/absolute/path/to/minimax-mcp/minimax_mcp.py"],
      "env": {
        "MINIMAX_API_KEY": "your_api_key_here"
      }
    }
  }
}

Using with mcporter CLI

# List available tools
mcporter list minimax --schema

# Web search
mcporter call minimax.minimax_web_search query="MiniMax AI API" --output json

# Image understanding (uses /v1/coding_plan/vlm directly)
mcporter call minimax.minimax_understand_image params='{"prompt": "What is in this image?", "image_source": "https://example.com/photo.jpg"}' --output json

# Text-to-speech (use English_expressive_narrator for best compatibility)
mcporter call minimax.minimax_text_to_speech params='{"text": "Hello world", "voice_id": "English_expressive_narrator"}' --output json

# Image generation
mcporter call minimax.minimax_generate_image params='{"prompt": "A sunset over the ocean", "aspect_ratio": "16:9"}' --output json

Note: minimax_understand_image downloads and encodes images before sending to the API, which can take time. When calling via mcporter, set the timeout explicitly for this tool: MCPORTER_CALL_TIMEOUT=120000 mcporter call minimax.minimax_understand_image ....

Tools

minimax_web_search

Search the web using MiniMax's search API.

Parameters:

• query (string, required) — Search query (3-5 keywords recommended)

• response_format (string) — Output format: markdown (default) or json

minimax_understand_image

Analyze images using MiniMax's vision model. The tool downloads remote images or reads local files, converts them to base64, and sends them directly to MiniMax's /v1/coding_plan/vlm API — no subprocess required.

Parameters:

• prompt (string, required) — Question or instruction about the image

• image_source (string, required) — URL (http/https), local file path, or base64 data URL

• response_format (string) — Output format: markdown (default) or json

Supported formats: JPEG, PNG, WebP

minimax_text_to_speech

Generate speech audio from text.

Parameters:

• text (string, required) — Text to convert (max 5000 characters)

• voice_id (string) — Voice selection (default: English_expressive_narrator)

• speed (float) — Speech speed 0.5-2.0 (default: 1.0)

Available Voices:

• English_expressive_narrator (default — confirmed working)

• Male_Narrator — may not be available on all API plans

• Female_Narrator — may not be available on all API plans

• english_expressive_c=clon — may not be available on all API plans

• english_expressive_n=clon — may not be available on all API plans

• male_narration_n=clon — may not be available on all API plans

Note: Only English_expressive_narrator is guaranteed to work. Other voice IDs may return "voice id not exist" depending on your MiniMax API plan. If you encounter this error, switch to the default voice.

minimax_generate_image

Generate images from text descriptions.

Parameters:

• prompt (string, required) — Image description (max 1500 characters)

• aspect_ratio (string) — Image dimensions (default: 1:1)

• n (int) — Number of images 1-9 (default: 1)

Aspect Ratios:

• 1:1 (1024x1024) — square

• 16:9 (1280x720) — widescreen

• 4:3 (1152x864) — standard

• 3:2 (1248x832) — photo

• 2:3 (832x1248) — portrait

• 3:4 (864x1152) — portrait tall

• 9:16 (720x1280) — story/vertical

• 21:9 (1344x576) — ultrawide

Configuration

Environment Variables

Claude Desktop App

For Claude Desktop App, add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "minimax": {
      "command": "python3",
      "args": ["/absolute/path/to/minimax-mcp/minimax_mcp.py"],
      "env": {
        "MINIMAX_API_KEY": "your_api_key_here"
      }
    }
  }
}

Security Notes

• Never commit your API key to version control

• Use environment variables to pass sensitive credentials

• The server reads MINIMAX_API_KEY from the environment, never from config files in the repo

Claude Desktop App

macOS: Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "minimax": {
      "command": "python3",
      "args": ["/absolute/path/to/minimax-mcp/minimax_mcp.py"],
      "env": {
        "MINIMAX_API_KEY": "your_api_key_here"
      }
    }
  }
}

Windows: Add to %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "minimax": {
      "command": "python",
      "args": ["C:\\path\\to\\minimax-mcp\\minimax_mcp.py"],
      "env": {
        "MINIMAX_API_KEY": "your_api_key_here"
      }
    }
  }
}

License

MIT