# Directory Structure
```
├── .env.example
├── .github
│ └── ISSUE_TEMPLATE
│ ├── Bad case about the model.yml
│ ├── Bug Report for MCP.yml
│ ├── Feature request.yml
│ └── Model Inquiry.yml
├── .gitignore
├── LICENSE
├── mcp_server_config_demo.json
├── minimax_mcp
│ ├── __init__.py
│ ├── __main__.py
│ ├── client.py
│ ├── const.py
│ ├── exceptions.py
│ ├── server.py
│ └── utils.py
├── pyproject.toml
├── README-CN.md
├── README.md
├── scripts
│ ├── build.sh
│ ├── deploy.sh
│ ├── dev.sh
│ ├── setup.sh
│ └── test.sh
├── setup.py
├── tests
│ ├── conftest.py
│ └── test_utils.py
└── uv.lock
```
# Files
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
1 | *.pyc
2 | *.pyo
3 | *.pyd
4 | *.pyw
5 | *.pyz
6 | *.pywz
7 |
8 | .env
9 | .venv
10 | .cursor
11 | .cursorignore
12 | dist/
13 | minimax_mcp.egg-info/
14 | .coverage
15 | coverage.xml
```
--------------------------------------------------------------------------------
/.env.example:
--------------------------------------------------------------------------------
```
1 | MINIMAX_API_KEY=PUT_YOUR_KEY_HERE
2 | #optional base path for output files
3 | MINIMAX_MCP_BASE_PATH=~/Desktop
4 | MINIMAX_API_HOST=https://api.minimax.chat
5 | #optional resource mode[url, local], default is url
6 | # MINIMAX_API_RESOURCE_MODE=local
```
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
```markdown
1 | 
2 |
3 | <div align="center" style="line-height: 1;">
4 | <a href="https://www.minimax.io" target="_blank" style="margin: 2px; color: var(--fgColor-default);">
5 | <img alt="Homepage" src="https://img.shields.io/badge/_Homepage-MiniMax-FF4040?style=flat-square&labelColor=2C3E50&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHhtbG5zOnhsaW5rPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5L3hsaW5rIiB2aWV3Qm94PSIwIDAgNDkwLjE2IDQxMS43Ij48ZGVmcz48c3R5bGU+LmNscy0xe2ZpbGw6I2ZmZjt9PC9zdHlsZT48L2RlZnM+PHBhdGggY2xhc3M9ImNscy0xIiBkPSJNMjMzLjQ1LDQwLjgxYTE3LjU1LDE3LjU1LDAsMSwwLTM1LjEsMFYzMzEuNTZhNDAuODIsNDAuODIsMCwwLDEtODEuNjMsMFYxNDVhMTcuNTUsMTcuNTUsMCwxLDAtMzUuMDksMHY3OS4wNmE0MC44Miw0MC44MiwwLDAsMS04MS42MywwVjE5NS40MmExMS42MywxMS42MywwLDAsMSwyMy4yNiwwdjI4LjY2YTE3LjU1LDE3LjU1LDAsMCwwLDM1LjEsMFYxNDVBNDAuODIsNDAuODIsMCwwLDEsMTQwLDE0NVYzMzEuNTZhMTcuNTUsMTcuNTUsMCwwLDAsMzUuMSwwVjIxNy41aDBWNDAuODFhNDAuODEsNDAuODEsMCwxLDEsODEuNjIsMFYyODEuNTZhMTEuNjMsMTEuNjMsMCwxLDEtMjMuMjYsMFptMjE1LjksNjMuNEE0MC44Niw0MC44NiwwLDAsMCw0MDguNTMsMTQ1VjMwMC44NWExNy41NSwxNy41NSwwLDAsMS0zNS4wOSwwdi0yNjBhNDAuODIsNDAuODIsMCwwLDAtODEuNjMsMFYzNzAuODlhMTcuNTUsMTcuNTUsMCwwLDEtMzUuMSwwVjMzMGExMS42MywxMS42MywwLDEsMC0yMy4yNiwwdjQwLjg2YTQwLjgxLDQwLjgxLDAsMCwwLDgxLjYyLDBWNDAuODFhMTcuNTUsMTcuNTUsMCwwLDEsMzUuMSwwdjI2MGE0MC44Miw0MC44MiwwLDAsMCw4MS42MywwVjE0NWExNy41NSwxNy41NSwwLDEsMSwzNS4xLDBWMjgxLjU2YTExLjYzLDExLjYzLDAsMCwwLDIzLjI2LDBWMTQ1QTQwLjg1LDQwLjg1LDAsMCwwLDQ0OS4zNSwxMDQuMjFaIi8+PC9zdmc+&logoWidth=20" style="display: inline-block; vertical-align: middle;"/>
6 | </a>
7 | <a href="https://arxiv.org/abs/2501.08313" target="_blank" style="margin: 2px;">
8 | <img alt="Paper" src="https://img.shields.io/badge/📖_Paper-MiniMax--01-FF4040?style=flat-square&labelColor=2C3E50" style="display: inline-block; vertical-align: middle;"/>
9 | </a>
10 | <a href="https://chat.minimax.io/" target="_blank" style="margin: 2px;">
11 | <img alt="Chat" src="https://img.shields.io/badge/_MiniMax_Chat-FF4040?style=flat-square&labelColor=2C3E50&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHhtbG5zOnhsaW5rPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5L3hsaW5rIiB2aWV3Qm94PSIwIDAgNDkwLjE2IDQxMS43Ij48ZGVmcz48c3R5bGU+LmNscy0xe2ZpbGw6I2ZmZjt9PC9zdHlsZT48L2RlZnM+PHBhdGggY2xhc3M9ImNscy0xIiBkPSJNMjMzLjQ1LDQwLjgxYTE3LjU1LDE3LjU1LDAsMSwwLTM1LjEsMFYzMzEuNTZhNDAuODIsNDAuODIsMCwwLDEtODEuNjMsMFYxNDVhMTcuNTUsMTcuNTUsMCwxLDAtMzUuMDksMHY3OS4wNmE0MC44Miw0MC44MiwwLDAsMS04MS42MywwVjE5NS40MmExMS42MywxMS42MywwLDAsMSwyMy4yNiwwdjI4LjY2YTE3LjU1LDE3LjU1LDAsMCwwLDM1LjEsMFYxNDVBNDAuODIsNDAuODIsMCwwLDEsMTQwLDE0NVYzMzEuNTZhMTcuNTUsMTcuNTUsMCwwLDAsMzUuMSwwVjIxNy41aDBWNDAuODFhNDAuODEsNDAuODEsMCwxLDEsODEuNjIsMFYyODEuNTZhMTEuNjMsMTEuNjMsMCwxLDEtMjMuMjYsMFptMjE1LjksNjMuNEE0MC44Niw0MC44NiwwLDAsMCw0MDguNTMsMTQ1VjMwMC44NWExNy41NSwxNy41NSwwLDAsMS0zNS4wOSwwdi0yNjBhNDAuODIsNDAuODIsMCwwLDAtODEuNjMsMFYzNzAuODlhMTcuNTUsMTcuNTUsMCwwLDEtMzUuMSwwVjMzMGExMS42MywxMS42MywwLDEsMC0yMy4yNiwwdjQwLjg2YTQwLjgxLDQwLjgxLDAsMCwwLDgxLjYyLDBWNDAuODFhMTcuNTUsMTcuNTUsMCwwLDEsMzUuMSwwdjI2MGE0MC44Miw0MC44MiwwLDAsMCw4MS42MywwVjE0NWExNy41NSwxNy41NSwwLDEsMSwzNS4xLDBWMjgxLjU2YTExLjYzLDExLjYzLDAsMCwwLDIzLjI2LDBWMTQ1QTQwLjg1LDQwLjg1LDAsMCwwLDQ0OS4zNSwxMDQuMjFaIi8+PC9zdmc+&logoWidth=20" style="display: inline-block; vertical-align: middle;"/>
12 | </a>
13 | <a href="https://www.minimax.io/platform" style="margin: 2px;">
14 | <img alt="API" src="https://img.shields.io/badge/⚡_API-Platform-FF4040?style=flat-square&labelColor=2C3E50" style="display: inline-block; vertical-align: middle;"/>
15 | </a>
16 | </div>
17 | <div align="center" style="line-height: 1;">
18 | <a href="https://huggingface.co/MiniMaxAI" target="_blank" style="margin: 2px;">
19 | <img alt="Hugging Face" src="https://img.shields.io/badge/🤗_Hugging_Face-MiniMax-FF4040?style=flat-square&labelColor=2C3E50" style="display: inline-block; vertical-align: middle;"/>
20 | </a>
21 | <a href="https://github.com/MiniMax-AI/MiniMax-AI.github.io/blob/main/images/wechat-qrcode.jpeg" target="_blank" style="margin: 2px;">
22 | <img alt="WeChat" src="https://img.shields.io/badge/_WeChat-MiniMax-FF4040?style=flat-square&labelColor=2C3E50" style="display: inline-block; vertical-align: middle;"/>
23 | </a>
24 | <a href="https://www.modelscope.cn/organization/MiniMax" target="_blank" style="margin: 2px;">
25 | <img alt="ModelScope" src="https://img.shields.io/badge/_ModelScope-MiniMax-FF4040?style=flat-square&labelColor=2C3E50" style="display: inline-block; vertical-align: middle;"/>
26 | </a>
27 | </div>
28 | <div align="center" style="line-height: 1;">
29 | <a href="https://github.com/MiniMax-AI/MiniMax-MCP/blob/main/LICENSE" style="margin: 2px;">
30 | <img alt="Code License" src="https://img.shields.io/badge/_Code_License-MIT-FF4040?style=flat-square&labelColor=2C3E50" style="display: inline-block; vertical-align: middle;"/>
31 | </a>
32 | </div>
33 |
34 | <p align="center">
35 | Official MiniMax Model Context Protocol (MCP) server that enables interaction with powerful Text to Speech and video/image generation APIs. This server allows MCP clients like <a href="https://www.anthropic.com/claude">Claude Desktop</a>, <a href="https://www.cursor.so">Cursor</a>, <a href="https://codeium.com/windsurf">Windsurf</a>, <a href="https://github.com/openai/openai-agents-python">OpenAI Agents</a> and others to generate speech, clone voices, generate video, generate image and more.
36 | </p>
37 |
38 | ## Documentation
39 | - [中文文档](README-CN.md)
40 | - [MiniMax-MCP-JS](https://github.com/MiniMax-AI/MiniMax-MCP-JS) - Official JavaScript implementation of MiniMax MCP
41 |
42 | ## Quickstart with MCP Client
43 | 1. Get your API key from [MiniMax](https://www.minimax.io/platform/user-center/basic-information/interface-key).
44 | 2. Install `uv` (Python package manager), install with `curl -LsSf https://astral.sh/uv/install.sh | sh` or see the `uv` [repo](https://github.com/astral-sh/uv) for additional install methods.
45 | 3. **Important**: The API host and key vary by region and must match; otherwise, you'll encounter an `Invalid API key` error.
46 |
47 | |Region| Global | Mainland |
48 | |:--|:-----|:-----|
49 | |MINIMAX_API_KEY| go get from [MiniMax Global](https://www.minimax.io/platform/user-center/basic-information/interface-key) | go get from [MiniMax](https://platform.minimaxi.com/user-center/basic-information/interface-key) |
50 | |MINIMAX_API_HOST| https://api.minimax.io | https://api.minimaxi.com |
51 |
52 |
53 | ### Claude Desktop
54 | Go to `Claude > Settings > Developer > Edit Config > claude_desktop_config.json` to include the following:
55 |
56 | ```
57 | {
58 | "mcpServers": {
59 | "MiniMax": {
60 | "command": "uvx",
61 | "args": [
62 | "minimax-mcp",
63 | "-y"
64 | ],
65 | "env": {
66 | "MINIMAX_API_KEY": "insert-your-api-key-here",
67 | "MINIMAX_MCP_BASE_PATH": "local-output-dir-path, such as /User/xxx/Desktop",
68 | "MINIMAX_API_HOST": "api host, https://api.minimax.io | https://api.minimaxi.com",
69 | "MINIMAX_API_RESOURCE_MODE": "optional, [url|local], url is default, audio/image/video are downloaded locally or provided in URL format"
70 | }
71 | }
72 | }
73 | }
74 |
75 | ```
76 | ⚠️ Warning: The API key needs to match the host. If an error "API Error: invalid api key" occurs, please check your api host:
77 | - Global Host：`https://api.minimax.io`
78 | - Mainland Host：`https://api.minimaxi.com`
79 |
80 | If you're using Windows, you will have to enable "Developer Mode" in Claude Desktop to use the MCP server. Click "Help" in the hamburger menu in the top left and select "Enable Developer Mode".
81 |
82 |
83 | ### Cursor
84 | Go to `Cursor -> Preferences -> Cursor Settings -> MCP -> Add new global MCP Server` to add above config.
85 |
86 | That's it. Your MCP client can now interact with MiniMax through these tools:
87 |
88 | ## Transport
89 | We support two transport types: stdio and sse.
90 | | stdio | SSE |
91 | |:-----|:-----|
92 | | Run locally | Can be deployed locally or in the cloud |
93 | | Communication through `stdout` | Communication through `network` |
94 | | Input: Supports processing `local files` or valid `URL` resources | Input: When deployed in the cloud, it is recommended to use `URL` for input |
95 |
96 | ## Available Tools
97 | | tool | description |
98 | |-|-|
99 | |`text_to_audio`|Convert text to audio with a given voice|
100 | |`list_voices`|List all voices available|
101 | |`voice_clone`|Clone a voice using provided audio files|
102 | |`generate_video`|Generate a video from a prompt|
103 | |`text_to_image`|Generate a image from a prompt|
104 | |`query_video_generation`|Query the result of video generation task|
105 | |`music_generation`|Generate a music track from a prompt and lyrics|
106 | |`voice_design`|Generate a voice from a prompt using preview text|
107 |
108 | ## Release Notes
109 |
110 | ### July 2, 2025
111 |
112 | #### 🆕 What's New
113 | - **Voice Design**: New `voice_design` tool - create custom voices from descriptive prompts with preview audio
114 | - **Video Enhancement**: Added `MiniMax-Hailuo-02` model with ultra-clear quality and duration/resolution controls
115 | - **Music Generation**: Enhanced `music_generation` tool powered by `music-1.5` model
116 |
117 | #### 📈 Enhanced Tools
118 | - `voice_design` - Generate personalized voices from text descriptions
119 | - `generate_video` - Now supports MiniMax-Hailuo-02 with 6s/10s duration and 768P/1080P resolution options
120 | - `music_generation` - High-quality music creation with music-1.5 model
121 |
122 | ## FAQ
123 | ### 1. invalid api key
124 | Please ensure your API key and API host are regionally aligned
125 | |Region| Global | Mainland |
126 | |:--|:-----|:-----|
127 | |MINIMAX_API_KEY| go get from [MiniMax Global](https://www.minimax.io/platform/user-center/basic-information/interface-key) | go get from [MiniMax](https://platform.minimaxi.com/user-center/basic-information/interface-key) |
128 | |MINIMAX_API_HOST| https://api.minimax.io | https://api.minimaxi.com |
129 |
130 | ### 2. spawn uvx ENOENT
131 | Please confirm its absolute path by running this command in your terminal:
132 | ```sh
133 | which uvx
134 | ```
135 | Once you obtain the absolute path (e.g., /usr/local/bin/uvx), update your configuration to use that path (e.g., "command": "/usr/local/bin/uvx").
136 |
137 | ### 3. How to use `generate_video` in async-mode
138 | Define completion rules before starting:
139 | <img src="https://public-cdn-video-data-algeng.oss-cn-wulanchabu.aliyuncs.com/cursor_rule2.png?x-oss-process=image/resize,p_50/format,webp" style="display: inline-block; vertical-align: middle;"/>
140 | Alternatively, these rules can be configured in your IDE settings (e.g., Cursor):
141 | <img src="https://public-cdn-video-data-algeng.oss-cn-wulanchabu.aliyuncs.com/cursor_video_rule.png?x-oss-process=image/resize,p_50/format,webp" style="display: inline-block; vertical-align: middle;"/>
142 |
143 |
144 | ## Example usage
145 |
146 | ⚠️ Warning: Using these tools may incur costs.
147 |
148 | ### 1. broadcast a segment of the evening news
149 | <img src="https://public-cdn-video-data-algeng.oss-cn-wulanchabu.aliyuncs.com/Snipaste_2025-04-09_20-07-53.png?x-oss-process=image/resize,p_50/format,webp" style="display: inline-block; vertical-align: middle;"/>
150 |
151 | ### 2. clone a voice
152 | <img src="https://public-cdn-video-data-algeng.oss-cn-wulanchabu.aliyuncs.com/Snipaste_2025-04-09_19-45-13.png?x-oss-process=image/resize,p_50/format,webp" style="display: inline-block; vertical-align: middle;"/>
153 |
154 | ### 3. generate a video
155 | <img src="https://public-cdn-video-data-algeng.oss-cn-wulanchabu.aliyuncs.com/Snipaste_2025-04-09_19-58-52.png?x-oss-process=image/resize,p_50/format,webp" style="display: inline-block; vertical-align: middle;"/>
156 | <img src="https://public-cdn-video-data-algeng.oss-cn-wulanchabu.aliyuncs.com/Snipaste_2025-04-09_19-59-43.png?x-oss-process=image/resize,p_50/format,webp" style="display: inline-block; vertical-align: middle; "/>
157 |
158 | ### 4. generate images
159 | <img src="https://public-cdn-video-data-algeng.oss-cn-wulanchabu.aliyuncs.com/gen_image.png?x-oss-process=image/resize,p_50/format,webp" style="display: inline-block; vertical-align: middle;"/>
160 | <img src="https://public-cdn-video-data-algeng.oss-cn-wulanchabu.aliyuncs.com/gen_image1.png?x-oss-process=image/resize,p_50/format,webp" style="display: inline-block; vertical-align: middle; "/>
161 |
```
--------------------------------------------------------------------------------
/scripts/build.sh:
--------------------------------------------------------------------------------
```bash
1 | #!/bin/bash
2 | rm -rf dist/ build/ *.egg-info/
3 | uv build
```
--------------------------------------------------------------------------------
/minimax_mcp/__init__.py:
--------------------------------------------------------------------------------
```python
1 | """Minimax MCP Server package."""
2 |
3 | __version__ = "0.0.17"
4 |
```
--------------------------------------------------------------------------------
/setup.py:
--------------------------------------------------------------------------------
```python
1 | from setuptools import setup, find_packages
2 |
3 | setup(
4 | packages=find_packages(),
5 | include_package_data=True,
6 | )
7 |
```
--------------------------------------------------------------------------------
/scripts/dev.sh:
--------------------------------------------------------------------------------
```bash
1 | #!/bin/bash
2 | uv run fastmcp dev minimax_mcp/server.py --with python-dotenv --with fuzzywuzzy --with python-Levenshtein --with sounddevice --with soundfile --with-editable .
```
--------------------------------------------------------------------------------
/tests/conftest.py:
--------------------------------------------------------------------------------
```python
1 | import pytest
2 | from pathlib import Path
3 | import tempfile
4 |
5 |
6 | @pytest.fixture
7 | def temp_dir():
8 | with tempfile.TemporaryDirectory() as temp_dir:
9 | yield Path(temp_dir)
10 |
11 |
12 | @pytest.fixture
13 | def sample_audio_file(temp_dir):
14 | audio_file = temp_dir / "test.mp3"
15 | audio_file.touch()
16 | return audio_file
17 |
18 |
19 | @pytest.fixture
20 | def sample_video_file(temp_dir):
21 | video_file = temp_dir / "test.mp4"
22 | video_file.touch()
23 | return video_file
24 |
```
--------------------------------------------------------------------------------
/scripts/deploy.sh:
--------------------------------------------------------------------------------
```bash
1 | #!/bin/bash
2 |
3 | # Check if environment argument is provided
4 | if [[ $# -lt 1 ]]; then
5 | echo "Usage: $0 [test|prod]"
6 | exit 1
7 | fi
8 |
9 | # Clean previous builds
10 | rm -rf dist/ build/ *.egg-info/
11 |
12 | # Build the package
13 | uv build
14 |
15 | if [ "$1" = "test" ]; then
16 | uv run twine upload --repository testpypi dist/* --verbose
17 | elif [ "$1" = "prod" ]; then
18 | uv run twine upload --repository pypi dist/*
19 | else
20 | echo "Please specify 'test' or 'prod' as the argument"
21 | exit 1
22 | fi
```
--------------------------------------------------------------------------------
/minimax_mcp/exceptions.py:
--------------------------------------------------------------------------------
```python
1 | """Custom exceptions for Minimax MCP."""
2 |
3 | class MinimaxAPIError(Exception):
4 | """Base exception for Minimax API errors."""
5 | pass
6 |
7 | class MinimaxAuthError(MinimaxAPIError):
8 | """Authentication related errors."""
9 | pass
10 |
11 | class MinimaxRequestError(MinimaxAPIError):
12 | """Request related errors."""
13 | pass
14 |
15 | class MinimaxTimeoutError(MinimaxAPIError):
16 | """Timeout related errors."""
17 | pass
18 |
19 | class MinimaxValidationError(MinimaxAPIError):
20 | """Validation related errors."""
21 | pass
22 |
23 | class MinimaxMcpError(MinimaxAPIError):
24 | pass
25 |
```
--------------------------------------------------------------------------------
/scripts/test.sh:
--------------------------------------------------------------------------------
```bash
1 | #!/bin/bash
2 |
3 | # Set default variables
4 | COVERAGE=true
5 | VERBOSE=false
6 | FAIL_FAST=false
7 |
8 | # Process command-line arguments
9 | while [[ $# -gt 0 ]]; do
10 | case $1 in
11 | --no-coverage)
12 | COVERAGE=false
13 | shift
14 | ;;
15 | --verbose|-v)
16 | VERBOSE=true
17 | shift
18 | ;;
19 | --fail-fast|-f)
20 | FAIL_FAST=true
21 | shift
22 | ;;
23 | *)
24 | echo "Unknown option: $1"
25 | echo "Usage: ./test.sh [--no-coverage] [--verbose|-v] [--fail-fast|-f]"
26 | exit 1
27 | ;;
28 | esac
29 | done
30 |
31 | # Build the command
32 | CMD="python -m pytest"
33 |
34 | if [ "$COVERAGE" = true ]; then
35 | CMD="$CMD --cov=minimax_mcp"
36 | fi
37 |
38 | if [ "$VERBOSE" = true ]; then
39 | CMD="$CMD -v"
40 | fi
41 |
42 | if [ "$FAIL_FAST" = true ]; then
43 | CMD="$CMD -x"
44 | fi
45 |
46 | # Run the tests
47 | echo "Running tests with command: $CMD"
48 | $CMD
```
--------------------------------------------------------------------------------
/scripts/setup.sh:
--------------------------------------------------------------------------------
```bash
1 | #!/bin/bash
2 |
3 | # Ensure uv is available
4 | if ! command -v uv &> /dev/null; then
5 | echo "Error: uv is not installed. Please install it first:"
6 | echo "pip install uv"
7 | exit 1
8 | fi
9 |
10 | # Create or update virtual environment
11 | echo "Creating/updating virtual environment..."
12 | uv venv .venv
13 |
14 | # Activate virtual environment based on shell
15 | if [[ "$SHELL" == */zsh ]]; then
16 | source .venv/bin/activate
17 | elif [[ "$SHELL" == */bash ]]; then
18 | source .venv/bin/activate
19 | else
20 | echo "Please activate the virtual environment manually:"
21 | echo "source .venv/bin/activate"
22 | fi
23 |
24 | # Install dependencies
25 | echo "Installing dependencies with uv..."
26 | uv pip install -e ".[dev]"
27 |
28 | # Install pre-commit hooks
29 | echo "Setting up pre-commit hooks..."
30 | pre-commit install
31 |
32 | echo "Setup complete! Virtual environment is ready."
```
--------------------------------------------------------------------------------
/mcp_server_config_demo.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "mcpServers": {
3 | "MiniMax": {
4 | "command": "uvx",
5 | "args": [
6 | "minimax-mcp"
7 | ],
8 | "env": {
9 | "MINIMAX_API_KEY": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTc0NTM3NjU1N30.nrmwo6orXJfyf63IqJCK4LiUXrq9r9ZELCY530Mu6sLyx_qNAVsJ3Q828Rqy6pwoQl6VFMMFaJG3kc6aIMEfVLo7xlB-4NbwMxYKhwtxyQL8g_agYqw-1aY4zr3uvgTZxafXt1dEjcuS5i9O9SuOXXofeqb0jAnb_dssaLfgHNKlKthJpjsg8G76ZULS7KCpm6GvPWR4mwIdH-i0IhBU6CVSWpBAYKVNHJ-FVN_HzN5UgGvHkDbOOggg6Ib1illYbx6zkb7_JYZ7Tek1erjvJi7IG8Keh4NHq5kcyROWBetO9W8_2if_nfO6XBhlJRECpEmYBONwroGw0nH6xNblQw",
10 | "MINIMAX_MCP_BASE_PATH": "~/Desktop",
11 | "MINIMAX_API_HOST": "https://api.minimax.chat",
12 | "MINIMAX_API_RESOURCE_MODE": "url"
13 | }
14 | }
15 | }
16 | }
```
--------------------------------------------------------------------------------
/minimax_mcp/const.py:
--------------------------------------------------------------------------------
```python
1 | # speech model default values
2 | DEFAULT_VOICE_ID = "female-shaonv"
3 | DEFAULT_SPEECH_MODEL = "speech-02-hd"
4 | DEFAULT_MUSIC_MODEL = "music-1.5"
5 | DEFAULT_SPEED = 1.0
6 | DEFAULT_VOLUME = 1.0
7 | DEFAULT_PITCH = 0
8 | DEFAULT_EMOTION = "happy"
9 | DEFAULT_SAMPLE_RATE = 32000
10 | DEFAULT_BITRATE = 128000
11 | DEFAULT_CHANNEL = 1
12 | DEFAULT_FORMAT = "mp3"
13 | DEFAULT_LANGUAGE_BOOST = "auto"
14 |
15 | # video model default values
16 | DEFAULT_T2V_MODEL = "T2V-01"
17 |
18 | # image model default values
19 | DEFAULT_T2I_MODEL = "image-01"
20 |
21 | # ENV variables
22 | ENV_MINIMAX_API_KEY = "MINIMAX_API_KEY"
23 | ENV_MINIMAX_API_HOST = "MINIMAX_API_HOST"
24 | ENV_MINIMAX_MCP_BASE_PATH = "MINIMAX_MCP_BASE_PATH"
25 | ENV_RESOURCE_MODE = "MINIMAX_API_RESOURCE_MODE"
26 |
27 | RESOURCE_MODE_LOCAL = "local" # save resource to local file system
28 | RESOURCE_MODE_URL = "url" # provide resource url
29 |
30 | ENV_FASTMCP_LOG_LEVEL = "FASTMCP_LOG_LEVEL"
```
--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/Feature request.yml:
--------------------------------------------------------------------------------
```yaml
1 | name: Feature Request
2 | description: Propose a new feature or enhancement for the project.
3 | title: "[request]: "
4 | labels: ["enhancement", "feature-request", "triage"]
5 | body:
6 | - type: markdown
7 | attributes:
8 | value: |
9 | Thank you for suggesting a new feature! Please provide the following details to help us understand your proposal.
10 |
11 | - type: input
12 | id: feature-about
13 | attributes:
14 | label: Basic Information - Feature about
15 | description: "Please briefly describe the feature, including the type of use and the framework, e.g., support Minimax-M1 in Ollama."
16 | placeholder: "e.g., support Minimax-M1 in Ollama."
17 | validations:
18 | required: true
19 |
20 | - type: textarea
21 | id: proposal
22 | attributes:
23 | label: Proposal
24 | description: |
25 | Please describe the feature you have requested and the rationale behind it.
26 | The following template is recommended. Feel free to modify it as you needed.
27 | value: |
28 | #### Introduction
29 | I would like that ...
30 |
31 | #### Rational
32 | Implementation of this feature will help the following usecase:
33 | - ...
34 | - ...
35 |
36 | #### Anything else
37 | I find ... has this feature and xxx can serve as a reference for implementation.
38 | validations:
39 | required: true
40 |
```
--------------------------------------------------------------------------------
/pyproject.toml:
--------------------------------------------------------------------------------
```toml
1 | [project]
2 | name = "minimax-mcp"
3 | version = "0.0.17"
4 | description = "Minimax MCP Server"
5 | authors = [
6 | { name = "Roy Wu", email = "[email protected]" },
7 | ]
8 | readme = "README.md"
9 | license = { file = "LICENSE" }
10 | classifiers = [
11 | "Development Status :: 4 - Beta",
12 | "Intended Audience :: Developers",
13 | "License :: OSI Approved :: MIT License",
14 | "Programming Language :: Python :: 3",
15 | "Programming Language :: Python :: 3.10",
16 | ]
17 | keywords = [
18 | "minimax",
19 | "mcp",
20 | "text-to-speech",
21 | "voice-cloning",
22 | "video-generation",
23 | ]
24 | requires-python = ">=3.10"
25 | dependencies = [
26 | "mcp[cli]>=1.6.0",
27 | "fastapi>=0.109.2",
28 | "uvicorn>=0.27.1",
29 | "python-dotenv>=1.0.1",
30 | "pydantic>=2.6.1",
31 | "httpx>=0.28.1",
32 | "fuzzywuzzy>=0.18.0",
33 | "python-Levenshtein>=0.25.0",
34 | "sounddevice>=0.5.1",
35 | "soundfile>=0.13.1",
36 | "requests>=2.31.0",
37 | ]
38 |
39 | [project.scripts]
40 | minimax-mcp = "minimax_mcp.server:main"
41 |
42 | [project.optional-dependencies]
43 | dev = [
44 | "pre-commit>=3.6.2",
45 | "ruff>=0.3.0",
46 | "fastmcp>=0.4.1",
47 | "pytest>=8.0.0",
48 | "pytest-cov>=4.1.0",
49 | "twine>=6.1.0",
50 | "build>=1.0.3",
51 | ]
52 |
53 | [build-system]
54 | requires = ["setuptools>=45", "wheel"]
55 | build-backend = "setuptools.build_meta"
56 |
57 | [tool.pytest.ini_options]
58 | testpaths = ["tests"]
59 | python_files = ["test_*.py"]
60 | addopts = "-v --cov=minimax_mcp --cov-report=term-missing"
61 |
```
--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/Model Inquiry.yml:
--------------------------------------------------------------------------------
```yaml
1 | name: Model Inquiry
2 | description: Ask a question about the open source models.
3 | title: "[Inquiry]: "
4 | labels: ["question", "triage"]
5 | body:
6 | - type: markdown
7 | attributes:
8 | value: |
9 | Thank you for reaching out! Please provide the following details to help us understand and address your inquiry about models.
10 |
11 | - type: input
12 | attributes:
13 | label: Basic Information - Models Used
14 | description: |
15 | Please list the model used, e.g., MiniMax-M1, speech-02-hd, etc.
16 | Our models can be referred at [HuggingFace](https://huggingface.co/MiniMaxAI) or [the official site](https://www.minimax.io/platform_overview).
17 | placeholder: "ex: MiniMax-M1"
18 | validations:
19 | required: true
20 |
21 | - type: checkboxes
22 | id: problem-validation
23 | attributes:
24 | label: Is this information known and solvable?
25 | options:
26 | - label: "I have checked [Minimax documentation](https://www.minimax.io/platform_overview) and found no solution."
27 | required: true
28 | - label: "I have searched existing issues and found no duplicates."
29 | required: true
30 |
31 |
32 | - type: textarea
33 | id: detailed-description
34 | attributes:
35 | label: Description
36 | description: "Please describe your question in detail here. If available, please paste relevant screenshots directly into this box."
37 | placeholder: |
38 | - Your detailed question or issue description.
39 | - Relevant context or background information.
40 | - (Paste screenshots directly below this text)
41 | validations:
42 | required: true
43 |
```
--------------------------------------------------------------------------------
/minimax_mcp/__main__.py:
--------------------------------------------------------------------------------
```python
1 | import os
2 | import json
3 | from pathlib import Path
4 | import sys
5 | from dotenv import load_dotenv
6 | import argparse
7 |
8 | load_dotenv()
9 |
10 |
11 | def get_claude_config_path() -> Path | None:
12 | """Get the Claude config directory based on platform."""
13 | if sys.platform == "win32":
14 | path = Path(Path.home(), "AppData", "Roaming", "Claude")
15 | elif sys.platform == "darwin":
16 | path = Path(Path.home(), "Library", "Application Support", "Claude")
17 | elif sys.platform.startswith("linux"):
18 | path = Path(
19 | os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config"), "Claude"
20 | )
21 | else:
22 | return None
23 |
24 | if path.exists():
25 | return path
26 | return None
27 |
28 |
29 | def get_python_path():
30 | return sys.executable
31 |
32 |
33 | def generate_config(api_key: str | None = None):
34 | module_dir = Path(__file__).resolve().parent
35 | server_path = module_dir / "server.py"
36 | python_path = get_python_path()
37 |
38 | final_api_key = api_key or os.environ.get("MINIMAX_API_KEY")
39 | if not final_api_key:
40 | print("Error: Minimax API key is required.")
41 | print("Please either:")
42 | print(" 1. Pass the API key using --api-key argument, or")
43 | print(" 2. Set the MINIMAX_API_KEY environment variable, or")
44 | print(" 3. Add MINIMAX_API_KEY to your .env file")
45 | sys.exit(1)
46 |
47 | config = {
48 | "mcpServers": {
49 | "Minimax": {
50 | "command": "uvx",
51 | "args": [
52 | "minimax-mcp",
53 | ],
54 |
55 | "env": {
56 | "MINIMAX_API_KEY": final_api_key,
57 | "MINIMAX_MCP_BASE_PATH": "",
58 | "MINIMAX_API_HOST": "https://api.minimax.chat",
59 | },
60 | }
61 | }
62 | }
63 |
64 | return config
65 |
66 |
67 | if __name__ == "__main__":
68 | parser = argparse.ArgumentParser()
69 | parser.add_argument(
70 | "--print",
71 | action="store_true",
72 | help="Print config to screen instead of writing to file",
73 | )
74 | parser.add_argument(
75 | "--api-key",
76 | help="Minimax API key (alternatively, set MINIMAX_API_KEY environment variable)",
77 | )
78 | parser.add_argument(
79 | "--config-path",
80 | type=Path,
81 | help="Custom path to Claude config directory",
82 | )
83 | args = parser.parse_args()
84 |
85 | config = generate_config(args.api_key)
86 |
87 | if args.print:
88 | print(json.dumps(config, indent=2))
89 | else:
90 | claude_path = args.config_path if args.config_path else get_claude_config_path()
91 | if claude_path is None:
92 | print(
93 | "Could not find Claude config path automatically. Please specify it using --config-path argument. The argument should be an absolute path of the claude_desktop_config.json file."
94 | )
95 | sys.exit(1)
96 |
97 | claude_path.mkdir(parents=True, exist_ok=True)
98 | print("Writing config to", claude_path / "claude_desktop_config.json")
99 | with open(claude_path / "claude_desktop_config.json", "w") as f:
100 | json.dump(config, f, indent=2)
101 |
```
--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/Bug Report for MCP.yml:
--------------------------------------------------------------------------------
```yaml
1 | name: Bug Report for MCP&API
2 | description: Report a bug related to MCP and API tasks to help us reproduce and fix the problem.
3 | title: "[Bug for MCP&API]: "
4 | labels: ["bug", "triage"]
5 | body:
6 | - type: markdown
7 | attributes:
8 | value: |
9 | Thank you for contributing to our project by reporting a bug! To help us understand and resolve the issue as quickly as possible, please provide the following details.
10 |
11 | - type: input
12 | attributes:
13 | label: Basic Information - Models Used
14 | description: |
15 | Please list the model used, e.g., MiniMax-M1, speech-02-hd, etc.
16 | Our models can be referred at [HuggingFace](https://huggingface.co/MiniMaxAI) or [the official site](https://www.minimax.io/platform_overview).
17 | placeholder: "ex: MiniMax-M1"
18 | validations:
19 | required: true
20 |
21 | - type: input
22 | id: scenario-description
23 | attributes:
24 | label: Basic Information - Scenario Description
25 | description: |
26 | Please briefly describe the scenario, including the framework or the platform,
27 | placeholder: "ex: Minimax-M1 cannot be called as MCP tools. "
28 | validations:
29 | required: false
30 |
31 | - type: checkboxes
32 | id: problem-validation
33 | attributes:
34 | label: Is this bug known and solvable?
35 | options:
36 | - label: "I have followed the GitHub READMEs for [`Minimax-MCP`](https://github.com/MiniMax-AI/MiniMax-MCP) and [`Minimax-MCP-JS`](https://github.com/MiniMax-AI/MiniMax-MCP-JS)."
37 | required: true
38 | - label: "I have checked the [official Minimax documentation](https://www.minimax.io/platform_overview) and [existing GitHub issues](https://github.com/MiniMax-AI/MiniMax-MCP/issues)，but found no solution."
39 | required: true
40 |
41 | - type: textarea
42 | attributes:
43 | label: Information about environment
44 | description: |
45 | Please provide information about you environment,
46 | e.g., the software versions and the information on the OS, GPUs, python packages(from pip list) if available.
47 | placeholder:
48 | "For example:
49 | - OS: Ubuntu 24.04
50 | - Python: Python 3.11
51 | - PyTorch: 2.6.0+cu124"
52 |
53 | validations:
54 | required: true
55 |
56 | - type: input
57 | id: trace-id
58 | attributes:
59 | label: Trace-ID in the request head
60 | description: "Please copy and paste the trace-ID of the problematic request."
61 | validations:
62 | required: true
63 |
64 | - type: textarea
65 | attributes:
66 | label: Description
67 | description: |
68 | Please **describe the bug** you have encountered when using the MCP tools or API, and **paste the screenshots** of the error or unexpected behaviour here.
69 | The following template is recommended.
70 | Feel free to modify as you needed.
71 | value: |
72 | #### Steps to reproduce
73 |
74 | This happens to Minimax_M1 and xxx.
75 | The bug can be reproduced with the following steps:
76 | 1. ...
77 | 2. ...
78 |
79 | The following example input & output can be used:
80 | ```
81 | system: ...
82 | user: ...
83 | ...
84 | ```
85 |
86 | #### Expected results
87 |
88 | The results are expected to be ...
89 |
90 | #### Actual behaviours
91 |
92 | The actual outputs are as follows: ...
93 |
94 | #### Error logs
95 |
96 | The error logs are as follows: ...
97 |
98 | ### The screenshots are as belows:
99 | validations:
100 | required: true
101 |
```
--------------------------------------------------------------------------------
/tests/test_utils.py:
--------------------------------------------------------------------------------
```python
1 | import pytest
2 | from pathlib import Path
3 | import tempfile
4 | from minimax_mcp.utils import (
5 | MinimaxMcpError,
6 | is_file_writeable,
7 | build_output_file,
8 | build_output_path,
9 | find_similar_filenames,
10 | try_find_similar_files,
11 | process_input_file,
12 | )
13 |
14 | def test_is_file_writeable():
15 | with tempfile.TemporaryDirectory() as temp_dir:
16 | temp_path = Path(temp_dir)
17 | assert is_file_writeable(temp_path) is True
18 | assert is_file_writeable(temp_path / "nonexistent.txt") is True
19 |
20 |
21 | def test_make_output_file():
22 | tool = "test"
23 | text = "hello world"
24 | output_path = Path("/tmp")
25 | result = build_output_file(tool, text, output_path, "mp3")
26 | assert result.name.startswith("test_hello")
27 | assert result.suffix == ".mp3"
28 |
29 |
30 | def test_make_output_path():
31 | # Test with temporary directory
32 | with tempfile.TemporaryDirectory() as temp_dir:
33 | result = build_output_path(temp_dir)
34 | assert result == Path(temp_dir)
35 | assert result.exists()
36 | assert result.is_dir()
37 |
38 | # Test with None output_directory (should use base_path)
39 | base_path = "/tmp/test_base"
40 | result = build_output_path(None, base_path, is_test=True)
41 | assert result == Path(base_path)
42 |
43 | # Test with relative output_directory
44 | base_path = "/tmp/test_base"
45 | result = build_output_path("subdir", base_path, is_test=True)
46 | assert result == Path(base_path) / "subdir"
47 |
48 | # Test with absolute output_directory (should ignore base_path)
49 | abs_path = "/absolute/path"
50 | result = build_output_path(abs_path, "/some/base/path", is_test=True)
51 | assert result == Path(abs_path)
52 |
53 | abs_path = "~/absolute/path"
54 | result = build_output_path(abs_path, "/some/base/path", is_test=True)
55 | assert result == Path(Path.home() / "absolute/path")
56 |
57 | # Test with None base_path (should use desktop)
58 | result = build_output_path(None, None, is_test=True)
59 | assert result == Path.home() / "Desktop"
60 |
61 |
62 |
63 | def test_find_similar_filenames():
64 | with tempfile.TemporaryDirectory() as temp_dir:
65 | temp_path = Path(temp_dir)
66 | test_file = temp_path / "test_file.txt"
67 | similar_file = temp_path / "test_file_2.txt"
68 | different_file = temp_path / "different.txt"
69 |
70 | test_file.touch()
71 | similar_file.touch()
72 | different_file.touch()
73 |
74 | results = find_similar_filenames(str(test_file), temp_path)
75 | assert len(results) > 0
76 | assert any(str(similar_file) in str(r[0]) for r in results)
77 |
78 |
79 | def test_try_find_similar_files():
80 | with tempfile.TemporaryDirectory() as temp_dir:
81 | temp_path = Path(temp_dir)
82 | test_file = temp_path / "test_file.mp3"
83 | similar_file = temp_path / "test_file_2.mp3"
84 | different_file = temp_path / "different.txt"
85 |
86 | test_file.touch()
87 | similar_file.touch()
88 | different_file.touch()
89 |
90 | results = try_find_similar_files(str(test_file), temp_path)
91 | assert len(results) > 0
92 | assert any(str(similar_file) in str(r) for r in results)
93 |
94 |
95 | def test_process_input_file():
96 | with tempfile.TemporaryDirectory() as temp_dir:
97 | temp_path = Path(temp_dir)
98 | test_file = temp_path / "test.mp3"
99 |
100 | with open(test_file, "wb") as f:
101 | f.write(b"\xff\xfb\x90\x64\x00")
102 |
103 | result = process_input_file(str(test_file))
104 | assert result == test_file
105 |
106 | with pytest.raises(MinimaxMcpError):
107 | process_input_file(str(temp_path / "nonexistent.mp3"))
108 |
```
--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/Bad case about the model.yml:
--------------------------------------------------------------------------------
```yaml
1 | name: Bad Case Report of the model
2 | description: Report a bug related to the model to help us reproduce and fix the problem.
3 | title: "[BadCase about the model]: "
4 |
5 | body:
6 | - type: markdown
7 | attributes:
8 | value: |
9 | Thank you for contributing to our project by reporting a bad case! To help us understand and resolve the issue as quickly as possible, please provide the following details.
10 |
11 | - type: input
12 | id: models-used
13 | attributes:
14 | label: Basic Information - Models Used
15 | description: |
16 | Please list the model used, e.g., MiniMax-M1, speech-02-hd, etc.
17 | (Note: You can refer to our models at [HuggingFace](https://huggingface.co/MiniMaxAI) or [the official site](https://www.minimax.io/platform_overview) for more details.)
18 | placeholder: "ex: MiniMax-M1"
19 | validations:
20 | required: true
21 |
22 | - type: input
23 | id: scenario-description
24 | attributes:
25 | label: Basic Information - Scenario Description
26 | description: |
27 | Please briefly describe the scenario, including the framework or the platform.
28 | placeholder: "ex: Minimax-M1 return the error related to xxx."
29 | validations:
30 | required: false
31 |
32 | - type: checkboxes
33 | id: problem-validation
34 | attributes:
35 | label: Is this badcase known and solvable?
36 | options:
37 | - label: "I have followed the [GitHub README](https://github.com/MiniMax-AI) of the model and found no duplicates in existing issues."
38 | required: true
39 | - label: "I have checked [Minimax documentation](https://www.minimax.io/platform_overview) and found no solution."
40 | required: true
41 |
42 | - type: textarea
43 | id: environment-info
44 | attributes:
45 | label: Information about environment
46 | description: |
47 | (Include software versions, OS, GPUs if applicable)
48 | placeholder: |
49 | For example:
50 | - OS: Ubuntu 24.04
51 | - Python: Python 3.11
52 | - PyTorch: 2.6.0+cu124
53 | validations:
54 | required: true
55 |
56 | - type: textarea
57 | id: call-execution-info # Consolidated field for call type and details
58 | attributes:
59 | label: Call & Execution Information
60 | description: |
61 | Please describe how you are interacting with the model and provide the relevant details in the box below:
62 | **Call Type**: (e.g., API Call, Deployment Call)
63 | **If API Call**: Please provide the `trace-ID` of the problematic request.
64 | **If Deployment Call**: Please provide the command used for deployment or inference.
65 | placeholder: |
66 | # Example for API Call:
67 | Call Type: API Call
68 | Trace-ID: abcdef1234567890
69 |
70 | # Example for Deployment Call:
71 | Call Type: Deployment Call
72 | Deployment Command: python run_inference.py --model my_model --config config.yaml
73 | validations:
74 | required: true
75 |
76 | - type: textarea
77 | id: description-of-bug
78 | attributes:
79 | label: Description
80 | description: |
81 | Please **describe the bad case** you have encountered and **paste the screenshots** if available.
82 | The following template is recommended (modify as needed):
83 | value: |
84 | ### Steps to reproduce
85 | The bug can be reproduced with the following steps:
86 | 1. ...
87 | 2. ...
88 |
89 | ### Expected behavior
90 | The results are expected to be: ...
91 |
92 | ### Actual behavior
93 | The actual outputs are as follows: ...
94 |
95 | ### Error logs
96 | The error logs are as follows:
97 | ```
98 | # Paste the related screenshots here
99 | ```
100 | validations:
101 | required: true
102 |
```
--------------------------------------------------------------------------------
/minimax_mcp/client.py:
--------------------------------------------------------------------------------
```python
1 | """Minimax API client base class."""
2 |
3 | import requests
4 | from typing import Any, Dict
5 | from minimax_mcp.exceptions import MinimaxAuthError, MinimaxRequestError
6 |
7 | class MinimaxAPIClient:
8 | """Base client for making requests to Minimax API."""
9 |
10 | def __init__(self, api_key: str, api_host: str):
11 | """Initialize the API client.
12 |
13 | Args:
14 | api_key: The API key for authentication
15 | api_host: The API host URL
16 | """
17 | self.api_key = api_key
18 | self.api_host = api_host
19 | self.session = requests.Session()
20 | self.session.headers.update({
21 | 'Authorization': f'Bearer {api_key}',
22 | 'MM-API-Source': 'Minimax-MCP'
23 | })
24 |
25 | def _make_request(
26 | self,
27 | method: str,
28 | endpoint: str,
29 | **kwargs
30 | ) -> Dict[str, Any]:
31 | """Make an HTTP request to the Minimax API.
32 |
33 | Args:
34 | method: HTTP method (GET, POST, etc.)
35 | endpoint: API endpoint path
36 | **kwargs: Additional arguments to pass to requests
37 |
38 | Returns:
39 | API response data as dictionary
40 |
41 | Raises:
42 | MinimaxAuthError: If authentication fails
43 | MinimaxRequestError: If the request fails
44 | """
45 | url = f"{self.api_host}{endpoint}"
46 |
47 | # Set Content-Type based on whether files are being uploaded
48 | files = kwargs.get('files')
49 | if not files:
50 | self.session.headers['Content-Type'] = 'application/json'
51 | else:
52 | # Remove Content-Type header for multipart/form-data
53 | # requests library will set it automatically with the correct boundary
54 | self.session.headers.pop('Content-Type', None)
55 |
56 | try:
57 | response = self.session.request(method, url, **kwargs)
58 |
59 | # Check for other HTTP errors
60 | response.raise_for_status()
61 |
62 | data = response.json()
63 |
64 | # Check API-specific error codes
65 | base_resp = data.get("base_resp", {})
66 | if base_resp.get("status_code") != 0:
67 | match base_resp.get("status_code"):
68 | case 1004:
69 | raise MinimaxAuthError(
70 | f"API Error: {base_resp.get('status_msg')}, please check your API key and API host."
71 | f"Trace-Id: {response.headers.get('Trace-Id')}"
72 | )
73 | case 2038:
74 | raise MinimaxRequestError(
75 | f"API Error: {base_resp.get('status_msg')}, should complete real-name verification on the open-platform(https://platform.minimaxi.com/user-center/basic-information)."
76 | f"Trace-Id: {response.headers.get('Trace-Id')}"
77 | )
78 | case _:
79 | raise MinimaxRequestError(
80 | f"API Error: {base_resp.get('status_code')}-{base_resp.get('status_msg')} "
81 | f"Trace-Id: {response.headers.get('Trace-Id')}"
82 | )
83 |
84 | return data
85 |
86 | except requests.exceptions.RequestException as e:
87 | raise MinimaxRequestError(f"Request failed: {str(e)}")
88 |
89 | def get(self, endpoint: str, **kwargs) -> Dict[str, Any]:
90 | """Make a GET request."""
91 | return self._make_request("GET", endpoint, **kwargs)
92 |
93 | def post(self, endpoint: str, **kwargs) -> Dict[str, Any]:
94 | """Make a POST request."""
95 | return self._make_request("POST", endpoint, **kwargs)
```
--------------------------------------------------------------------------------
/minimax_mcp/utils.py:
--------------------------------------------------------------------------------
```python
1 | import os
2 | from pathlib import Path
3 | from datetime import datetime
4 | from fuzzywuzzy import fuzz
5 | import shutil
6 | import subprocess
7 | from typing import Iterator, Union
8 | from minimax_mcp.const import *
9 | from minimax_mcp.exceptions import MinimaxMcpError
10 |
11 |
12 | def is_file_writeable(path: Path) -> bool:
13 | if path.exists():
14 | return os.access(path, os.W_OK)
15 | parent_dir = path.parent
16 | return os.access(parent_dir, os.W_OK)
17 |
18 |
19 | def build_output_file(
20 | tool: str, text: str, output_path: Path, extension: str, full_id: bool = False
21 | ) -> Path:
22 | id = text if full_id else text[:10]
23 |
24 | output_file_name = f"{tool}_{id.replace(' ', '_')}_{datetime.now().strftime('%Y%m%d_%H%M%S')}.{extension}"
25 | return output_path / output_file_name
26 |
27 |
28 | def build_output_path(
29 | output_directory: str | None, base_path: str | None = None, is_test: bool = False
30 | ) -> Path:
31 | # Set default base_path to desktop if not provided
32 | if base_path is None:
33 | base_path = str(Path.home() / "Desktop")
34 |
35 | # Handle output path based on output_directory
36 | if output_directory is None:
37 | output_path = Path(os.path.expanduser(base_path))
38 | elif not os.path.isabs(os.path.expanduser(output_directory)):
39 | output_path = Path(os.path.expanduser(base_path)) / Path(output_directory)
40 | else:
41 | output_path = Path(os.path.expanduser(output_directory))
42 |
43 | # Safety checks and directory creation
44 | if is_test:
45 | return output_path
46 | if not is_file_writeable(output_path):
47 | raise MinimaxMcpError(f"Directory ({output_path}) is not writeable")
48 | output_path.mkdir(parents=True, exist_ok=True)
49 | return output_path
50 |
51 |
52 | def find_similar_filenames(
53 | target_file: str, directory: Path, threshold: int = 70
54 | ) -> list[tuple[str, int]]:
55 | """
56 | Find files with names similar to the target file using fuzzy matching.
57 |
58 | Args:
59 | target_file (str): The reference filename to compare against
60 | directory (str): Directory to search in (defaults to current directory)
61 | threshold (int): Similarity threshold (0 to 100, where 100 is identical)
62 |
63 | Returns:
64 | list: List of similar filenames with their similarity scores
65 | """
66 | target_filename = os.path.basename(target_file)
67 | similar_files = []
68 | for root, _, files in os.walk(directory):
69 | for filename in files:
70 | if (
71 | filename == target_filename
72 | and os.path.join(root, filename) == target_file
73 | ):
74 | continue
75 | similarity = fuzz.token_sort_ratio(target_filename, filename)
76 |
77 | if similarity >= threshold:
78 | file_path = Path(root) / filename
79 | similar_files.append((file_path, similarity))
80 |
81 | similar_files.sort(key=lambda x: x[1], reverse=True)
82 |
83 | return similar_files
84 |
85 |
86 | def try_find_similar_files(
87 | filename: str, directory: Path, take_n: int = 5
88 | ) -> list[Path]:
89 | similar_files = find_similar_filenames(filename, directory)
90 | if not similar_files:
91 | return []
92 |
93 | filtered_files = []
94 |
95 | for path, _ in similar_files[:take_n]:
96 | if check_audio_file(path):
97 | filtered_files.append(path)
98 |
99 | return filtered_files
100 |
101 |
102 | def check_audio_file(path: Path) -> bool:
103 | audio_extensions = {
104 | ".wav",
105 | ".mp3",
106 | ".m4a",
107 | ".aac",
108 | ".ogg",
109 | ".flac",
110 | ".mp4",
111 | ".avi",
112 | ".mov",
113 | ".wmv",
114 | }
115 | return path.suffix.lower() in audio_extensions
116 |
117 |
118 | def process_input_file(file_path: str, audio_content_check: bool = True) -> Path:
119 | if not os.path.isabs(file_path) and not os.environ.get(ENV_MINIMAX_MCP_BASE_PATH):
120 | raise MinimaxMcpError(
121 | "File path must be an absolute path if MINIMAX_MCP_BASE_PATH is not set"
122 | )
123 | path = Path(file_path)
124 | if not path.exists() and path.parent.exists():
125 | parent_directory = path.parent
126 | similar_files = try_find_similar_files(path.name, parent_directory)
127 | similar_files_formatted = ",".join([str(file) for file in similar_files])
128 | if similar_files:
129 | raise MinimaxMcpError(
130 | f"File ({path}) does not exist. Did you mean any of these files: {similar_files_formatted}?"
131 | )
132 | raise MinimaxMcpError(f"File ({path}) does not exist")
133 | elif not path.exists():
134 | raise MinimaxMcpError(f"File ({path}) does not exist")
135 | elif not path.is_file():
136 | raise MinimaxMcpError(f"File ({path}) is not a file")
137 |
138 | if audio_content_check and not check_audio_file(path):
139 | raise MinimaxMcpError(f"File ({path}) is not an audio or video file")
140 | return path
141 |
142 |
143 | def is_installed(lib_name: str) -> bool:
144 | return shutil.which(lib_name) is not None
145 |
146 |
147 | def play(
148 | audio: Union[bytes, Iterator[bytes]]
149 | ) -> None:
150 | if isinstance(audio, Iterator):
151 | audio = b"".join(audio)
152 |
153 | if not is_installed("ffplay"):
154 | message = (
155 | "ffplay from ffmpeg not found, necessary to play audio. "
156 | "mac: install it with 'brew install ffmpeg'. "
157 | "linux or windows: install it from https://ffmpeg.org/"
158 | )
159 | raise ValueError(message)
160 |
161 | args = ["ffplay", "-autoexit", "-", "-nodisp"]
162 | proc = subprocess.Popen(
163 | args=args,
164 | stdout=subprocess.PIPE,
165 | stdin=subprocess.PIPE,
166 | stderr=subprocess.PIPE,
167 | )
168 | out, err = proc.communicate(input=audio)
169 |
170 | proc.poll()
171 |
172 |
173 |
```
--------------------------------------------------------------------------------
/README-CN.md:
--------------------------------------------------------------------------------
```markdown
1 | 
2 |
3 | <div align="center" style="line-height: 1;">
4 | <a href="https://www.minimax.io" target="_blank" style="margin: 2px; color: var(--fgColor-default);">
5 | <img alt="Homepage" src="https://img.shields.io/badge/_Homepage-MiniMax-FF4040?style=flat-square&labelColor=2C3E50&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHhtbG5zOnhsaW5rPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5L3hsaW5rIiB2aWV3Qm94PSIwIDAgNDkwLjE2IDQxMS43Ij48ZGVmcz48c3R5bGU+LmNscy0xe2ZpbGw6I2ZmZjt9PC9zdHlsZT48L2RlZnM+PHBhdGggY2xhc3M9ImNscy0xIiBkPSJNMjMzLjQ1LDQwLjgxYTE3LjU1LDE3LjU1LDAsMSwwLTM1LjEsMFYzMzEuNTZhNDAuODIsNDAuODIsMCwwLDEtODEuNjMsMFYxNDVhMTcuNTUsMTcuNTUsMCwxLDAtMzUuMDksMHY3OS4wNmE0MC44Miw0MC44MiwwLDAsMS04MS42MywwVjE5NS40MmExMS42MywxMS42MywwLDAsMSwyMy4yNiwwdjI4LjY2YTE3LjU1LDE3LjU1LDAsMCwwLDM1LjEsMFYxNDVBNDAuODIsNDAuODIsMCwwLDEsMTQwLDE0NVYzMzEuNTZhMTcuNTUsMTcuNTUsMCwwLDAsMzUuMSwwVjIxNy41aDBWNDAuODFhNDAuODEsNDAuODEsMCwxLDEsODEuNjIsMFYyODEuNTZhMTEuNjMsMTEuNjMsMCwxLDEtMjMuMjYsMFptMjE1LjksNjMuNEE0MC44Niw0MC44NiwwLDAsMCw0MDguNTMsMTQ1VjMwMC44NWExNy41NSwxNy41NSwwLDAsMS0zNS4wOSwwdi0yNjBhNDAuODIsNDAuODIsMCwwLDAtODEuNjMsMFYzNzAuODlhMTcuNTUsMTcuNTUsMCwwLDEtMzUuMSwwVjMzMGExMS42MywxMS42MywwLDEsMC0yMy4yNiwwdjQwLjg2YTQwLjgxLDQwLjgxLDAsMCwwLDgxLjYyLDBWNDAuODFhMTcuNTUsMTcuNTUsMCwwLDEsMzUuMSwwdjI2MGE0MC44Miw0MC44MiwwLDAsMCw4MS42MywwVjE0NWExNy41NSwxNy41NSwwLDEsMSwzNS4xLDBWMjgxLjU2YTExLjYzLDExLjYzLDAsMCwwLDIzLjI2LDBWMTQ1QTQwLjg1LDQwLjg1LDAsMCwwLDQ0OS4zNSwxMDQuMjFaIi8+PC9zdmc+&logoWidth=20" style="display: inline-block; vertical-align: middle;"/>
6 | </a>
7 | <a href="https://arxiv.org/abs/2501.08313" target="_blank" style="margin: 2px;">
8 | <img alt="Paper" src="https://img.shields.io/badge/📖_Paper-MiniMax--01-FF4040?style=flat-square&labelColor=2C3E50" style="display: inline-block; vertical-align: middle;"/>
9 | </a>
10 | <a href="https://chat.minimax.io/" target="_blank" style="margin: 2px;">
11 | <img alt="Chat" src="https://img.shields.io/badge/_MiniMax_Chat-FF4040?style=flat-square&labelColor=2C3E50&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHhtbG5zOnhsaW5rPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5L3hsaW5rIiB2aWV3Qm94PSIwIDAgNDkwLjE2IDQxMS43Ij48ZGVmcz48c3R5bGU+LmNscy0xe2ZpbGw6I2ZmZjt9PC9zdHlsZT48L2RlZnM+PHBhdGggY2xhc3M9ImNscy0xIiBkPSJNMjMzLjQ1LDQwLjgxYTE3LjU1LDE3LjU1LDAsMSwwLTM1LjEsMFYzMzEuNTZhNDAuODIsNDAuODIsMCwwLDEtODEuNjMsMFYxNDVhMTcuNTUsMTcuNTUsMCwxLDAtMzUuMDksMHY3OS4wNmE0MC44Miw0MC44MiwwLDAsMS04MS42MywwVjE5NS40MmExMS42MywxMS42MywwLDAsMSwyMy4yNiwwdjI4LjY2YTE3LjU1LDE3LjU1LDAsMCwwLDM1LjEsMFYxNDVBNDAuODIsNDAuODIsMCwwLDEsMTQwLDE0NVYzMzEuNTZhMTcuNTUsMTcuNTUsMCwwLDAsMzUuMSwwVjIxNy41aDBWNDAuODFhNDAuODEsNDAuODEsMCwxLDEsODEuNjIsMFYyODEuNTZhMTEuNjMsMTEuNjMsMCwxLDEtMjMuMjYsMFptMjE1LjksNjMuNEE0MC44Niw0MC44NiwwLDAsMCw0MDguNTMsMTQ1VjMwMC44NWExNy41NSwxNy41NSwwLDAsMS0zNS4wOSwwdi0yNjBhNDAuODIsNDAuODIsMCwwLDAtODEuNjMsMFYzNzAuODlhMTcuNTUsMTcuNTUsMCwwLDEtMzUuMSwwVjMzMGExMS42MywxMS42MywwLDEsMC0yMy4yNiwwdjQwLjg2YTQwLjgxLDQwLjgxLDAsMCwwLDgxLjYyLDBWNDAuODFhMTcuNTUsMTcuNTUsMCwwLDEsMzUuMSwwdjI2MGE0MC44Miw0MC44MiwwLDAsMCw4MS42MywwVjE0NWExNy41NSwxNy41NSwwLDEsMSwzNS4xLDBWMjgxLjU2YTExLjYzLDExLjYzLDAsMCwwLDIzLjI2LDBWMTQ1QTQwLjg1LDQwLjg1LDAsMCwwLDQ0OS4zNSwxMDQuMjFaIi8+PC9zdmc+&logoWidth=20" style="display: inline-block; vertical-align: middle;"/>
12 | </a>
13 | <a href="https://www.minimax.io/platform" style="margin: 2px;">
14 | <img alt="API" src="https://img.shields.io/badge/⚡_API-Platform-FF4040?style=flat-square&labelColor=2C3E50" style="display: inline-block; vertical-align: middle;"/>
15 | </a>
16 | </div>
17 | <div align="center" style="line-height: 1;">
18 | <a href="https://huggingface.co/MiniMaxAI" target="_blank" style="margin: 2px;">
19 | <img alt="Hugging Face" src="https://img.shields.io/badge/🤗_Hugging_Face-MiniMax-FF4040?style=flat-square&labelColor=2C3E50" style="display: inline-block; vertical-align: middle;"/>
20 | </a>
21 | <a href="https://github.com/MiniMax-AI/MiniMax-AI.github.io/blob/main/images/wechat-qrcode.jpeg" target="_blank" style="margin: 2px;">
22 | <img alt="WeChat" src="https://img.shields.io/badge/_WeChat-MiniMax-FF4040?style=flat-square&labelColor=2C3E50" style="display: inline-block; vertical-align: middle;"/>
23 | </a>
24 | <a href="https://www.modelscope.cn/organization/MiniMax" target="_blank" style="margin: 2px;">
25 | <img alt="ModelScope" src="https://img.shields.io/badge/_ModelScope-MiniMax-FF4040?style=flat-square&labelColor=2C3E50" style="display: inline-block; vertical-align: middle;"/>
26 | </a>
27 | </div>
28 | <div align="center" style="line-height: 1;">
29 | <a href="https://github.com/MiniMax-AI/MiniMax-MCP/blob/main/LICENSE" style="margin: 2px;">
30 | <img alt="Code License" src="https://img.shields.io/badge/_Code_License-MIT-FF4040?style=flat-square&labelColor=2C3E50" style="display: inline-block; vertical-align: middle;"/>
31 | </a>
32 | </div>
33 |
34 | <p align="center" style="line-height: 1.5; font-size: 18px; margin: 4px auto; text-decoration: underline;"><a href="README.md">English Version</a></p>
35 |
36 | <p align="center">
37 | MiniMax官方模型上下文协议(MCP)服务器，支持与强大的文本转语音和视频/图像生成API交互。允许MCP客户端如<a href="https://www.anthropic.com/claude">Claude Desktop</a>、<a href="https://www.cursor.so">Cursor</a>、<a href="https://codeium.com/windsurf">Windsurf</a>、<a href="https://github.com/openai/openai-agents-python">OpenAI Agents</a>等生成语音、克隆声音、生成视频、生成图像等功能。
38 | </p>
39 |
40 | ## Documentation
41 | - [English Documentation](README.md)
42 | - [MiniMax-MCP-JS](https://github.com/MiniMax-AI/MiniMax-MCP-JS) - MiniMax MCP的官方JavaScript版本
43 |
44 | ## 快速开始使用 MCP 客户端
45 | 1. 从[MiniMax国内开放平台](https://platform.minimaxi.com/user-center/basic-information/interface-key)｜[MiniMax国际开放平台](https://www.minimax.io/platform/user-center/basic-information/interface-key)获取你的 API 密钥。
46 | 2. 安装`uv`（Python包管理器），使用`curl -LsSf https://astral.sh/uv/install.sh | sh`安装或查看`uv` [仓库](https://github.com/astral-sh/uv)获取其他安装方法。
47 | 3. **重要提示: API的服务器地址和密钥在不同区域有所不同**，两者需要匹配，否则会有 `invalid api key` 的错误
48 |
49 | |地区| 国际 | 国内 |
50 | |:--|:-----|:-----|
51 | |MINIMAX_API_KEY| 获取密钥 [MiniMax国际版](https://www.minimax.io/platform/user-center/basic-information/interface-key) | 获取密钥 [MiniMax](https://platform.minimaxi.com/user-center/basic-information/interface-key) |
52 | |MINIMAX_API_HOST| https://api.minimax.io | https://api.minimaxi.com |
53 |
54 |
55 | ### Claude Desktop
56 | 前往`Claude > Settings > Developer > Edit Config > claude_desktop_config.json`包含以下内容：
57 |
58 | ```
59 | {
60 | "mcpServers": {
61 | "MiniMax": {
62 | "command": "uvx",
63 | "args": [
64 | "minimax-mcp"
65 | ],
66 | "env": {
67 | "MINIMAX_API_KEY": "填写你的API密钥",
68 | "MINIMAX_MCP_BASE_PATH": "本地输出目录路径，如/User/xxx/Desktop",
69 | "MINIMAX_API_HOST": "填写API Host, https://api.minimaxi.com 或 https://api.minimax.io",
70 | "MINIMAX_API_RESOURCE_MODE": "可选配置，资源生成后的提供方式, 可选项为 [url|local], 默认为 url"
71 | }
72 | }
73 | }
74 | }
75 | ```
76 |
77 |
78 | ⚠️ 注意：API Key需要与Host匹配。如果出现"API Error: invalid api key"错误，请检查您的API Host：
79 | - 国际版Host：`https://api.minimax.io`
80 | - 国内版Host：`https://api.minimaxi.com`
81 |
82 | 如果你使用Windows，你需要在Claude Desktop中启用"开发者模式"才能使用MCP服务器。点击左上角汉堡菜单中的"Help"，然后选择"Enable Developer Mode"。
83 |
84 |
85 | ### Cursor
86 | 前往`Cursor -> Preferences -> Cursor Settings -> MCP -> Add new global MCP Server`添加上述配置。
87 |
88 | 你的MCP客户端现在可以通过Claude Desktop和Cursor等这些工具与MiniMax交互：
89 |
90 | ## Transport
91 | 我们支持两种传输方式: stdio and sse.
92 | | stdio | SSE |
93 | |:-----|:-----|
94 | | 在本地部署运行 | 本地或云端部署均可 |
95 | |通过 stdout 进行通信| 通过网络通信|
96 | |输入：支持处理本地文件，或有效的URL资源| 输入: 若部署在云端，建议使用URL进行输入|
97 |
98 | ## 可用方法
99 | | 方法 | 描述 |
100 | |-|-|
101 | |`text_to_audio`|使用指定音色将文本生成音频|
102 | |`list_voices`|查询所有可用音色|
103 | |`voice_clone`|根据指定音频文件克隆音色|
104 | |`generate_video`|根据指定 prompt 生成视频|
105 | |`text_to_image`|根据指定 prompt 生成图片|
106 | |`music_generation`|根据指定 prompt 和歌词生成音乐|
107 | |`voice_design`|根据指定 prompt 生成音色和试听文本|
108 |
109 | ## 更新日志
110 |
111 | ### 2025年7月2日
112 |
113 | #### 🆕 新增功能
114 | - **音色设计**: 新增 `voice_design` 工具 - 根据描述性提示词创建自定义音色并生成试听音频
115 | - **视频生成增强**: 新增 `MiniMax-Hailuo-02` 模型，支持超清画质和时长/分辨率控制
116 | - **音乐生成**: 采用 `music-1.5` 模型增强 `music_generation` 工具
117 |
118 | #### 📈 功能增强
119 | - `voice_design` - 根据文本描述生成个性化音色
120 | - `generate_video` - 现在支持 MiniMax-Hailuo-02 模型，可选择 6s/10s 时长和 768P/1080P 分辨率
121 | - `music_generation` - 采用 music-1.5 模型进行高质量音乐创作
122 |
123 | ## FAQ
124 | ### 1. invalid api key
125 | 请检查你获取的 API Key 和填写的 API Host 是否是同一地区的：
126 | |地区| 国际 | 国内 |
127 | |:--|:-----|:-----|
128 | |MINIMAX_API_KEY| 获取密钥 [MiniMax国际版](https://www.minimax.io/platform/user-center/basic-information/interface-key) | 获取密钥 [MiniMax](https://platform.minimaxi.com/user-center/basic-information/interface-key) |
129 | |MINIMAX_API_HOST| https://api.minimax.io | https://api.minimaxi.com
130 |
131 | ### 2. spawn uvx ENOENT
132 | 请在你的终端输入一下命令，查看uvx命令的绝对路径：
133 | ```sh
134 | which uvx
135 | ```
136 | 如果得到如下的输出 (如：/usr/local/bin/uvx)，更新mcp配置 ("command": "/usr/local/bin/uvx").
137 |
138 | ### 3. 如何用 `generate_video` 工具异步生成视频
139 | 在对话前设置一些规则:
140 | <img src="https://public-cdn-video-data-algeng.oss-cn-wulanchabu.aliyuncs.com/cursor_rule2.png?x-oss-process=image/resize,p_50/format,webp" style="display: inline-block; vertical-align: middle;"/>
141 | 或者放到本地客户端的规则中 (以 Cursor 为例):
142 | <img src="https://public-cdn-video-data-algeng.oss-cn-wulanchabu.aliyuncs.com/cursor_video_rule.png?x-oss-process=image/resize,p_50/format,webp" style="display: inline-block; vertical-align: middle;"/>
143 |
144 |
145 | ## 使用示例
146 |
147 | ⚠️ 注意：使用这些工具可能会产生费用。
148 |
149 | ### 1. 播报晚间新闻片段
150 | <img src="https://public-cdn-video-data-algeng.oss-cn-wulanchabu.aliyuncs.com/Snipaste_2025-04-09_20-07-53.png?x-oss-process=image/resize,p_50/format,webp" style="display: inline-block; vertical-align: middle;"/>
151 |
152 | ### 2. 克隆声音
153 | <img src="https://public-cdn-video-data-algeng.oss-cn-wulanchabu.aliyuncs.com/Snipaste_2025-04-09_19-45-13.png?x-oss-process=image/resize,p_50/format,webp" style="display: inline-block; vertical-align: middle;"/>
154 |
155 | ### 3. 生成视频
156 | <img src="https://public-cdn-video-data-algeng.oss-cn-wulanchabu.aliyuncs.com/Snipaste_2025-04-09_19-58-52.png?x-oss-process=image/resize,p_50/format,webp" style="display: inline-block; vertical-align: middle;"/>
157 | <img src="https://public-cdn-video-data-algeng.oss-cn-wulanchabu.aliyuncs.com/Snipaste_2025-04-09_19-59-43.png?x-oss-process=image/resize,p_50/format,webp" style="display: inline-block; vertical-align: middle; "/>
158 |
159 | ### 4. 生成图像
160 | <img src="https://public-cdn-video-data-algeng.oss-cn-wulanchabu.aliyuncs.com/gen_image.png?x-oss-process=image/resize,p_50/format,webp" style="display: inline-block; vertical-align: middle;"/>
161 | <img src="https://public-cdn-video-data-algeng.oss-cn-wulanchabu.aliyuncs.com/gen_image1.png?x-oss-process=image/resize,p_50/format,webp" style="display: inline-block; vertical-align: middle; "/>
162 |
```
--------------------------------------------------------------------------------
/minimax_mcp/server.py:
--------------------------------------------------------------------------------
```python
1 | """
2 | MiniMax MCP Server
3 |
4 | ⚠️ IMPORTANT: This server connects to Minimax API endpoints which may involve costs.
5 | Any tool that makes an API call is clearly marked with a cost warning. Please follow these guidelines:
6 |
7 | 1. Only use these tools when users specifically ask for them
8 | 2. For audio generation tools, be mindful that text length affects the cost
9 | 3. Voice cloning features are charged upon first use after cloning
10 |
11 | Note: Tools without cost warnings are free to use as they only read existing data.
12 | """
13 |
14 | import os
15 | import base64
16 | import requests
17 | import time
18 | from dotenv import load_dotenv
19 | from mcp.server.fastmcp import FastMCP
20 | from mcp.types import TextContent
21 | from minimax_mcp.utils import (
22 | build_output_path,
23 | build_output_file,
24 | process_input_file,
25 | play
26 | )
27 | from pathlib import Path
28 |
29 | from minimax_mcp.const import *
30 | from minimax_mcp.exceptions import MinimaxAPIError, MinimaxRequestError
31 | from minimax_mcp.client import MinimaxAPIClient
32 |
33 | load_dotenv()
34 | api_key = os.getenv(ENV_MINIMAX_API_KEY)
35 | base_path = os.getenv(ENV_MINIMAX_MCP_BASE_PATH) or "~/Desktop"
36 | api_host = os.getenv(ENV_MINIMAX_API_HOST)
37 | resource_mode = os.getenv(ENV_RESOURCE_MODE) or RESOURCE_MODE_URL
38 | fastmcp_log_level = os.getenv(ENV_FASTMCP_LOG_LEVEL) or "WARNING"
39 |
40 | if not api_key:
41 | raise ValueError("MINIMAX_API_KEY environment variable is required")
42 | if not api_host:
43 | raise ValueError("MINIMAX_API_HOST environment variable is required")
44 |
45 | mcp = FastMCP("Minimax",log_level=fastmcp_log_level)
46 | api_client = MinimaxAPIClient(api_key, api_host)
47 |
48 |
49 | @mcp.tool(
50 | description="""Convert text to audio with a given voice and save the output audio file to a given directory.
51 | Directory is optional, if not provided, the output file will be saved to $HOME/Desktop.
52 | Voice id is optional, if not provided, the default voice will be used.
53 |
54 | COST WARNING: This tool makes an API call to Minimax which may incur costs. Only use when explicitly requested by the user.
55 |
56 | Args:
57 | text (str): The text to convert to speech.
58 | voice_id (str, optional): The id of the voice to use. For example, "male-qn-qingse"/"audiobook_female_1"/"cute_boy"/"Charming_Lady"...
59 | model (string, optional): The model to use.
60 | speed (float, optional): Speed of the generated audio. Controls the speed of the generated speech. Values range from 0.5 to 2.0, with 1.0 being the default speed.
61 | vol (float, optional): Volume of the generated audio. Controls the volume of the generated speech. Values range from 0 to 10, with 1 being the default volume.
62 | pitch (int, optional): Pitch of the generated audio. Controls the speed of the generated speech. Values range from -12 to 12, with 0 being the default speed.
63 | emotion (str, optional): Emotion of the generated audio. Controls the emotion of the generated speech. Values range ["happy", "sad", "angry", "fearful", "disgusted", "surprised", "neutral"], with "happy" being the default emotion.
64 | sample_rate (int, optional): Sample rate of the generated audio. Controls the sample rate of the generated speech. Values range [8000,16000,22050,24000,32000,44100] with 32000 being the default sample rate.
65 | bitrate (int, optional): Bitrate of the generated audio. Controls the bitrate of the generated speech. Values range [32000,64000,128000,256000] with 128000 being the default bitrate.
66 | channel (int, optional): Channel of the generated audio. Controls the channel of the generated speech. Values range [1, 2] with 1 being the default channel.
67 | format (str, optional): Format of the generated audio. Controls the format of the generated speech. Values range ["pcm", "mp3","flac"] with "mp3" being the default format.
68 | language_boost (str, optional): Language boost of the generated audio. Controls the language boost of the generated speech. Values range ['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'] with "auto" being the default language boost.
69 | output_directory (str): The directory to save the audio to.
70 |
71 | Returns:
72 | Text content with the path to the output file and name of the voice used.
73 | """
74 | )
75 | def text_to_audio(
76 | text: str,
77 | output_directory: str = None,
78 | voice_id: str = DEFAULT_VOICE_ID,
79 | model: str = DEFAULT_SPEECH_MODEL,
80 | speed: float = DEFAULT_SPEED,
81 | vol: float = DEFAULT_VOLUME,
82 | pitch: int = DEFAULT_PITCH,
83 | emotion: str = DEFAULT_EMOTION,
84 | sample_rate: int = DEFAULT_SAMPLE_RATE,
85 | bitrate: int = DEFAULT_BITRATE,
86 | channel: int = DEFAULT_CHANNEL,
87 | format: str = DEFAULT_FORMAT,
88 | language_boost: str = DEFAULT_LANGUAGE_BOOST,
89 | ):
90 | if not text:
91 | raise MinimaxRequestError("Text is required.")
92 |
93 | payload = {
94 | "model": model,
95 | "text": text,
96 | "voice_setting": {
97 | "voice_id": voice_id,
98 | "speed": speed,
99 | "vol": vol,
100 | "pitch": pitch,
101 | "emotion": emotion
102 | },
103 | "audio_setting": {
104 | "sample_rate": sample_rate,
105 | "bitrate": bitrate,
106 | "format": format,
107 | "channel": channel
108 | },
109 | "language_boost": language_boost
110 | }
111 | if resource_mode == RESOURCE_MODE_URL:
112 | payload["output_format"] = "url"
113 | try:
114 | response_data = api_client.post("/v1/t2a_v2", json=payload)
115 | audio_data = response_data.get('data', {}).get('audio', '')
116 |
117 | if not audio_data:
118 | raise MinimaxRequestError(f"Failed to get audio data from response")
119 | if resource_mode == RESOURCE_MODE_URL:
120 | return TextContent(
121 | type="text",
122 | text=f"Success. Audio URL: {audio_data}"
123 | )
124 | # hex->bytes
125 | audio_bytes = bytes.fromhex(audio_data)
126 |
127 | # save audio to file
128 | output_path = build_output_path(output_directory, base_path)
129 | output_file_name = build_output_file("t2a", text, output_path, format)
130 | output_path.parent.mkdir(parents=True, exist_ok=True)
131 |
132 | with open(output_path / output_file_name, "wb") as f:
133 | f.write(audio_bytes)
134 |
135 | return TextContent(
136 | type="text",
137 | text=f"Success. File saved as: {output_path / output_file_name}. Voice used: {voice_id}",
138 | )
139 |
140 | except MinimaxAPIError as e:
141 | return TextContent(
142 | type="text",
143 | text=f"Failed to generate audio: {str(e)}"
144 | )
145 |
146 |
147 | @mcp.tool(
148 | description="""List all voices available.
149 |
150 | Args:
151 | voice_type (str, optional): The type of voices to list. Values range ["all", "system", "voice_cloning"], with "all" being the default.
152 | Returns:
153 | Text content with the list of voices.
154 | """
155 | )
156 | def list_voices(
157 | voice_type: str = "all"
158 | ):
159 | try:
160 | response_data = api_client.post("/v1/get_voice", json={'voice_type': voice_type})
161 |
162 | system_voices = response_data.get('system_voice', []) or []
163 | voice_cloning_voices = response_data.get('voice_cloning', []) or []
164 | system_voice_list = []
165 | voice_cloning_voice_list = []
166 |
167 | for voice in system_voices:
168 | system_voice_list.append(f"Name: {voice.get('voice_name')}, ID: {voice.get('voice_id')}")
169 | for voice in voice_cloning_voices:
170 | voice_cloning_voice_list.append(f"Name: {voice.get('voice_name')}, ID: {voice.get('voice_id')}")
171 |
172 | return TextContent(
173 | type="text",
174 | text=f"Success. System Voices: {system_voice_list}, Voice Cloning Voices: {voice_cloning_voice_list}"
175 | )
176 |
177 | except MinimaxAPIError as e:
178 | return TextContent(
179 | type="text",
180 | text=f"Failed to list voices: {str(e)}"
181 | )
182 |
183 |
184 | @mcp.tool(
185 | description="""Clone a voice using provided audio files. The new voice will be charged upon first use.
186 |
187 | COST WARNING: This tool makes an API call to Minimax which may incur costs. Only use when explicitly requested by the user.
188 |
189 | Args:
190 | voice_id (str): The id of the voice to use.
191 | file (str): The path to the audio file to clone or a URL to the audio file.
192 | text (str, optional): The text to use for the demo audio.
193 | is_url (bool, optional): Whether the file is a URL. Defaults to False.
194 | output_directory (str): The directory to save the demo audio to.
195 | Returns:
196 | Text content with the voice id of the cloned voice.
197 | """
198 | )
199 | def voice_clone(
200 | voice_id: str,
201 | file: str,
202 | text: str,
203 | output_directory: str = None,
204 | is_url: bool = False
205 | ) -> TextContent:
206 | try:
207 | # step1: upload file
208 | if is_url:
209 | # download file from url
210 | response = requests.get(file, stream=True)
211 | response.raise_for_status()
212 | files = {'file': ('audio_file.mp3', response.raw, 'audio/mpeg')}
213 | data = {'purpose': 'voice_clone'}
214 | response_data = api_client.post("/v1/files/upload", files=files, data=data)
215 | else:
216 | # open and upload file
217 | if not os.path.exists(file):
218 | raise MinimaxRequestError(f"Local file does not exist: {file}")
219 | with open(file, 'rb') as f:
220 | files = {'file': f}
221 | data = {'purpose': 'voice_clone'}
222 | response_data = api_client.post("/v1/files/upload", files=files, data=data)
223 |
224 | file_id = response_data.get("file",{}).get("file_id")
225 | if not file_id:
226 | raise MinimaxRequestError(f"Failed to get file_id from upload response")
227 |
228 | # step2: clone voice
229 | payload = {
230 | "file_id": file_id,
231 | "voice_id": voice_id,
232 | }
233 | if text:
234 | payload["text"] = text
235 | payload["model"] = DEFAULT_SPEECH_MODEL
236 |
237 | response_data = api_client.post("/v1/voice_clone", json=payload)
238 |
239 | if not response_data.get("demo_audio"):
240 | return TextContent(
241 | type="text",
242 | text=f"Voice cloned successfully: Voice ID: {voice_id}"
243 | )
244 | if resource_mode == RESOURCE_MODE_URL:
245 | return TextContent(
246 | type="text",
247 | text=f"Success. Demo audio URL: {response_data.get('demo_audio')}"
248 | )
249 | # step3: download demo audio
250 | output_path = build_output_path(output_directory, base_path)
251 | output_file_name = build_output_file("voice_clone", text, output_path, "wav")
252 | output_path.parent.mkdir(parents=True, exist_ok=True)
253 |
254 | with open(output_path / output_file_name, "wb") as f:
255 | f.write(requests.get(response_data.get("demo_audio")).content)
256 |
257 | return TextContent(
258 | type="text",
259 | text=f"Voice cloned successfully: Voice ID: {voice_id}, demo audio saved as: {output_path / output_file_name}"
260 | )
261 |
262 | except MinimaxAPIError as e:
263 | return TextContent(
264 | type="text",
265 | text=f"Failed to clone voice: {str(e)}"
266 | )
267 | except (IOError, requests.RequestException) as e:
268 | return TextContent(
269 | type="text",
270 | text=f"Failed to handle files: {str(e)}"
271 | )
272 |
273 |
274 | @mcp.tool(
275 | description="""Play an audio file. Supports WAV and MP3 formats. Not supports video.
276 |
277 | Args:
278 | input_file_path (str): The path to the audio file to play.
279 | is_url (bool, optional): Whether the audio file is a URL.
280 | Returns:
281 | Text content with the path to the audio file.
282 | """
283 | )
284 | def play_audio(input_file_path: str, is_url: bool = False) -> TextContent:
285 | if is_url:
286 | play(requests.get(input_file_path).content)
287 | return TextContent(type="text", text=f"Successfully played audio file: {input_file_path}")
288 | else:
289 | file_path = process_input_file(input_file_path)
290 | play(open(file_path, "rb").read())
291 | return TextContent(type="text", text=f"Successfully played audio file: {file_path}")
292 |
293 |
294 | @mcp.tool(
295 | description="""Generate a video from a prompt.
296 |
297 | COST WARNING: This tool makes an API call to Minimax which may incur costs. Only use when explicitly requested by the user.
298 |
299 | Args:
300 | model (str, optional): The model to use. Values range ["T2V-01", "T2V-01-Director", "I2V-01", "I2V-01-Director", "I2V-01-live", "MiniMax-Hailuo-02"]. "Director" supports inserting instructions for camera movement control. "I2V" for image to video. "T2V" for text to video. "MiniMax-Hailuo-02" is the latest model with best effect, ultra-clear quality and precise response.
301 | prompt (str): The prompt to generate the video from. When use Director model, the prompt supports 15 Camera Movement Instructions (Enumerated Values)
302 | -Truck: [Truck left], [Truck right]
303 | -Pan: [Pan left], [Pan right]
304 | -Push: [Push in], [Pull out]
305 | -Pedestal: [Pedestal up], [Pedestal down]
306 | -Tilt: [Tilt up], [Tilt down]
307 | -Zoom: [Zoom in], [Zoom out]
308 | -Shake: [Shake]
309 | -Follow: [Tracking shot]
310 | -Static: [Static shot]
311 | first_frame_image (str): The first frame image. The model must be "I2V" Series.
312 | duration (int, optional): The duration of the video. The model must be "MiniMax-Hailuo-02". Values can be 6 and 10.
313 | resolution (str, optional): The resolution of the video. The model must be "MiniMax-Hailuo-02". Values range ["768P", "1080P"]
314 | output_directory (str): The directory to save the video to.
315 | async_mode (bool, optional): 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.
316 | Returns:
317 | Text content with the path to the output video file.
318 | """
319 | )
320 | def generate_video(
321 | model: str = DEFAULT_T2V_MODEL,
322 | prompt: str = "",
323 | first_frame_image = None,
324 | duration: int = None,
325 | resolution: str = None,
326 | output_directory: str = None,
327 | async_mode: bool = False
328 | ):
329 | try:
330 | if not prompt:
331 | raise MinimaxRequestError("Prompt is required")
332 |
333 | # check first_frame_image
334 | if first_frame_image:
335 | if not isinstance(first_frame_image, str):
336 | raise MinimaxRequestError(f"First frame image must be a string, got {type(first_frame_image)}")
337 | if not first_frame_image.startswith(("http://", "https://", "data:")):
338 | # if local image, convert to dataurl
339 | if not os.path.exists(first_frame_image):
340 | raise MinimaxRequestError(f"First frame image does not exist: {first_frame_image}")
341 | with open(first_frame_image, "rb") as f:
342 | image_data = f.read()
343 | first_frame_image = f"data:image/jpeg;base64,{base64.b64encode(image_data).decode('utf-8')}"
344 |
345 | # step1: submit video generation task
346 | payload = {
347 | "model": model,
348 | "prompt": prompt
349 | }
350 | if first_frame_image:
351 | payload["first_frame_image"] = first_frame_image
352 | if duration:
353 | payload["duration"] = duration
354 | if resolution:
355 | payload["resolution"] = resolution
356 | response_data = api_client.post("/v1/video_generation", json=payload)
357 | task_id = response_data.get("task_id")
358 | if not task_id:
359 | raise MinimaxRequestError("Failed to get task_id from response")
360 |
361 | if async_mode:
362 | return TextContent(
363 | type="text",
364 | text=f"Success. Video generation task submitted: Task ID: {task_id}. Please use `query_video_generation` tool to check the status of the task and get the result."
365 | )
366 |
367 | # step2: wait for video generation task to complete
368 | file_id = None
369 | max_retries = 30 # 10 minutes total (30 * 20 seconds)
370 | retry_interval = 20 # seconds
371 |
372 |
373 | # MiniMax-Hailuo-02 model has a longer processing time, so we need to wait for a longer time
374 | if model == "MiniMax-Hailuo-02":
375 | max_retries = 60
376 |
377 | for attempt in range(max_retries):
378 | status_response = api_client.get(f"/v1/query/video_generation?task_id={task_id}")
379 | status = status_response.get("status")
380 |
381 | if status == "Fail":
382 | raise MinimaxRequestError(f"Video generation failed for task_id: {task_id}")
383 | elif status == "Success":
384 | file_id = status_response.get("file_id")
385 | if file_id:
386 | break
387 | raise MinimaxRequestError(f"Missing file_id in success response for task_id: {task_id}")
388 |
389 | # Still processing, wait and retry
390 | time.sleep(retry_interval)
391 |
392 | if not file_id:
393 | raise MinimaxRequestError(f"Failed to get file_id for task_id: {task_id}")
394 |
395 | # step3: fetch video result
396 | file_response = api_client.get(f"/v1/files/retrieve?file_id={file_id}")
397 | download_url = file_response.get("file", {}).get("download_url")
398 |
399 | if not download_url:
400 | raise MinimaxRequestError(f"Failed to get download URL for file_id: {file_id}")
401 | if resource_mode == RESOURCE_MODE_URL:
402 | return TextContent(
403 | type="text",
404 | text=f"Success. Video URL: {download_url}"
405 | )
406 | # step4: download and save video
407 | output_path = build_output_path(output_directory, base_path)
408 | output_file_name = build_output_file("video", task_id, output_path, "mp4", True)
409 | output_path.parent.mkdir(parents=True, exist_ok=True)
410 |
411 | video_response = requests.get(download_url)
412 | video_response.raise_for_status()
413 |
414 | with open(output_path / output_file_name, "wb") as f:
415 | f.write(video_response.content)
416 |
417 | return TextContent(
418 | type="text",
419 | text=f"Success. Video saved as: {output_path / output_file_name}"
420 | )
421 |
422 | except MinimaxAPIError as e:
423 | return TextContent(
424 | type="text",
425 | text=f"Failed to generate video: {str(e)}"
426 | )
427 | except (IOError, requests.RequestException) as e:
428 | return TextContent(
429 | type="text",
430 | text=f"Failed to handle video file: {str(e)}"
431 | )
432 | except Exception as e:
433 | return TextContent(
434 | type="text",
435 | text=f"Unexpected error while generating video: {str(e)}"
436 | )
437 |
438 |
439 | @mcp.tool(
440 | description="""Query the status of a video generation task.
441 |
442 | Args:
443 | task_id (str): The task ID to query. Should be the task_id returned by `generate_video` tool if `async_mode` is True.
444 | output_directory (str): The directory to save the video to.
445 | Returns:
446 | Text content with the status of the task.
447 | """
448 | )
449 | def query_video_generation(task_id: str, output_directory: str = None) -> TextContent:
450 | try:
451 | file_id = None
452 | response_data = api_client.get(f"/v1/query/video_generation?task_id={task_id}")
453 | status = response_data.get("status")
454 | if status == "Fail":
455 | return TextContent(
456 | type="text",
457 | text=f"Video generation FAILED for task_id: {task_id}"
458 | )
459 | elif status == "Success":
460 | file_id = response_data.get("file_id")
461 | if not file_id:
462 | raise MinimaxRequestError(f"Missing file_id in success response for task_id: {task_id}")
463 | else:
464 | return TextContent(
465 | type="text",
466 | text=f"Video generation task is still processing: Task ID: {task_id}"
467 | )
468 | file_response = api_client.get(f"/v1/files/retrieve?file_id={file_id}")
469 | download_url = file_response.get("file", {}).get("download_url")
470 | if not download_url:
471 | raise MinimaxRequestError(f"Failed to get download URL for file_id: {file_id}")
472 | if resource_mode == RESOURCE_MODE_URL:
473 | return TextContent(
474 | type="text",
475 | text=f"Success. Video URL: {download_url}"
476 | )
477 | output_path = build_output_path(output_directory, base_path)
478 | output_file_name = build_output_file("video", task_id, output_path, "mp4", True)
479 | output_path.parent.mkdir(parents=True, exist_ok=True)
480 |
481 | video_response = requests.get(download_url)
482 | video_response.raise_for_status()
483 |
484 | with open(output_path / output_file_name, "wb") as f:
485 | f.write(video_response.content)
486 |
487 | return TextContent(
488 | type="text",
489 | text=f"Success. Video saved as: {output_path / output_file_name}"
490 | )
491 | except MinimaxAPIError as e:
492 | return TextContent(
493 | type="text",
494 | text=f"Failed to query video generation status: {str(e)}"
495 | )
496 |
497 |
498 | @mcp.tool(
499 | description="""Generate a image from a prompt.
500 |
501 | COST WARNING: This tool makes an API call to Minimax which may incur costs. Only use when explicitly requested by the user.
502 |
503 | Args:
504 | model (str, optional): The model to use. Values range ["image-01"], with "image-01" being the default.
505 | prompt (str): The prompt to generate the image from.
506 | aspect_ratio (str, optional): The aspect ratio of the image. Values range ["1:1", "16:9","4:3", "3:2", "2:3", "3:4", "9:16", "21:9"], with "1:1" being the default.
507 | n (int, optional): The number of images to generate. Values range [1, 9], with 1 being the default.
508 | prompt_optimizer (bool, optional): Whether to optimize the prompt. Values range [True, False], with True being the default.
509 | output_directory (str): The directory to save the image to.
510 | Returns:
511 | Text content with the path to the output image file.
512 | """
513 | )
514 | def text_to_image(
515 | model: str = DEFAULT_T2I_MODEL,
516 | prompt: str = "",
517 | aspect_ratio: str = "1:1",
518 | n: int = 1,
519 | prompt_optimizer: bool = True,
520 | output_directory: str = None,
521 | ):
522 | try:
523 | if not prompt:
524 | raise MinimaxRequestError("Prompt is required")
525 |
526 | payload = {
527 | "model": model,
528 | "prompt": prompt,
529 | "aspect_ratio": aspect_ratio,
530 | "n": n,
531 | "prompt_optimizer": prompt_optimizer
532 | }
533 |
534 | response_data = api_client.post("/v1/image_generation", json=payload)
535 | image_urls = response_data.get("data",{}).get("image_urls",[])
536 |
537 | if not image_urls:
538 | raise MinimaxRequestError("No images generated")
539 | if resource_mode == RESOURCE_MODE_URL:
540 | return TextContent(
541 | type="text",
542 | text=f"Success. Image URLs: {image_urls}"
543 | )
544 | output_path = build_output_path(output_directory, base_path)
545 | output_file_names = []
546 |
547 | for i, image_url in enumerate(image_urls):
548 | output_file_name = build_output_file("image", f"{i}_{prompt}", output_path, "jpg")
549 | output_path.parent.mkdir(parents=True, exist_ok=True)
550 |
551 | image_response = requests.get(image_url)
552 | image_response.raise_for_status()
553 |
554 | with open(output_file_name, 'wb') as f:
555 | f.write(image_response.content)
556 | output_file_names.append(output_file_name)
557 |
558 | return TextContent(
559 | type="text",
560 | text=f"Success. Images saved as: {output_file_names}"
561 | )
562 |
563 | except MinimaxAPIError as e:
564 | return TextContent(
565 | type="text",
566 | text=f"Failed to generate images: {str(e)}"
567 | )
568 | except (IOError, requests.RequestException) as e:
569 | return TextContent(
570 | type="text",
571 | text=f"Failed to save images: {str(e)}"
572 | )
573 |
574 | @mcp.tool(
575 | description="""Create a music generation task using AI models. Generate music from prompt and lyrics.
576 |
577 | COST WARNING: This tool makes an API call to Minimax which may incur costs. Only use when explicitly requested by the user.
578 |
579 | Args:
580 | prompt (str): Music creation inspiration describing style, mood, scene, etc.
581 | Example: "Pop music, sad, suitable for rainy nights". Character range: [10, 300]
582 | lyrics (str): Song lyrics for music generation.
583 | Use newline (\\n) to separate each line of lyrics. Supports lyric structure tags [Intro][Verse][Chorus][Bridge][Outro]
584 | to enhance musicality. Character range: [10, 600] (each Chinese character, punctuation, and letter counts as 1 character)
585 | stream (bool, optional): Whether to enable streaming mode. Defaults to False
586 | sample_rate (int, optional): Sample rate of generated music. Values: [16000, 24000, 32000, 44100]
587 | bitrate (int, optional): Bitrate of generated music. Values: [32000, 64000, 128000, 256000]
588 | format (str, optional): Format of generated music. Values: ["mp3", "wav", "pcm"]. Defaults to "mp3"
589 | output_directory (str, optional): Directory to save the generated music file
590 |
591 | Note: Currently supports generating music up to 1 minute in length.
592 |
593 | Returns:
594 | Text content with the path to the generated music file or generation status.
595 | """
596 | )
597 | def music_generation(
598 | prompt: str,
599 | lyrics: str,
600 | sample_rate: int = DEFAULT_SAMPLE_RATE,
601 | bitrate: int = DEFAULT_BITRATE,
602 | format: str = DEFAULT_FORMAT,
603 | output_directory: str = None
604 | ) -> TextContent:
605 | try:
606 | # prompt and lyrics params check
607 | if not prompt:
608 | raise MinimaxRequestError("Prompt is required.")
609 | if not lyrics:
610 | raise MinimaxRequestError("Lyrics is required.")
611 |
612 | # Build request payload
613 | payload = {
614 | "model": DEFAULT_MUSIC_MODEL,
615 | "prompt": prompt,
616 | "lyrics": lyrics,
617 | "audio_setting": {
618 | "sample_rate": sample_rate,
619 | "bitrate": bitrate,
620 | "format": format
621 | },
622 | }
623 | if resource_mode == RESOURCE_MODE_URL:
624 | payload["output_format"] = "url"
625 |
626 | # Call music generation API
627 | response_data = api_client.post("/v1/music_generation", json=payload)
628 |
629 | # Handle response
630 | data = response_data.get('data', {})
631 | audio_hex = data.get('audio', '')
632 |
633 | if resource_mode == RESOURCE_MODE_URL:
634 | return TextContent(
635 | type="text",
636 | text=f"Success. Music url: {audio_hex}"
637 | )
638 |
639 | output_path = build_output_path(output_directory, base_path)
640 | output_file_name = build_output_file("music", f"{prompt}", output_path, format)
641 | output_path.parent.mkdir(parents=True, exist_ok=True)
642 |
643 | # hex->bytes
644 | audio_bytes = bytes.fromhex(audio_hex)
645 |
646 | # save audio to file
647 | with open(output_path / output_file_name, "wb") as f:
648 | f.write(audio_bytes)
649 |
650 | return TextContent(
651 | type="text",
652 | text=f"Success. Music saved as: {output_path / output_file_name}"
653 | )
654 |
655 | except MinimaxAPIError as e:
656 | return TextContent(
657 | type="text",
658 | text=f"Failed to generate music: {str(e)}"
659 | )
660 | except (IOError, requests.RequestException) as e:
661 | return TextContent(
662 | type="text",
663 | text=f"Failed to save music: {str(e)}"
664 | )
665 |
666 | @mcp.tool(
667 | description="""Generate a voice based on description prompts.
668 |
669 | COST WARNING: This tool makes an API call to Minimax which may incur costs. Only use when explicitly requested by the user.
670 |
671 | Args:
672 | prompt (str): The prompt to generate the voice from.
673 | preview_text (str): The text to preview the voice.
674 | voice_id (str, optional): The id of the voice to use. For example, "male-qn-qingse"/"audiobook_female_1"/"cute_boy"/"Charming_Lady"...
675 | output_directory (str, optional): The directory to save the voice to.
676 | Returns:
677 | Text content with the path to the output voice file.
678 | """
679 | )
680 | def voice_design(
681 | prompt: str,
682 | preview_text: str,
683 | voice_id: str = None,
684 | output_directory: str = None,
685 | ):
686 | try:
687 | if not prompt:
688 | raise MinimaxRequestError("prompt is required")
689 | if not preview_text:
690 | raise MinimaxRequestError("preview_text is required")
691 |
692 | # Build request payload
693 | payload = {
694 | "prompt": prompt,
695 | "preview_text": preview_text
696 | }
697 |
698 | # Add voice_id if provided
699 | if voice_id:
700 | payload["voice_id"] = voice_id
701 |
702 | # Call voice design API
703 | response_data = api_client.post("/v1/voice_design", json=payload)
704 |
705 | # Get the response data
706 | generated_voice_id = response_data.get('voice_id', '')
707 | trial_audio_hex = response_data.get('trial_audio', '')
708 |
709 | if not generated_voice_id:
710 | raise MinimaxRequestError("No voice generated")
711 | if resource_mode == RESOURCE_MODE_URL:
712 | return TextContent(
713 | type="text",
714 | text=f"Success. Voice ID generated: {generated_voice_id}, Trial Audio: {trial_audio_hex}"
715 | )
716 |
717 | # hex->bytes
718 | audio_bytes = bytes.fromhex(trial_audio_hex)
719 |
720 | # save audio to file
721 | output_path = build_output_path(output_directory, base_path)
722 | output_file_name = build_output_file("voice_design", preview_text, output_path, "mp3")
723 | output_path.parent.mkdir(parents=True, exist_ok=True)
724 |
725 | with open(output_path / output_file_name, "wb") as f:
726 | f.write(audio_bytes)
727 |
728 | return TextContent(
729 | type="text",
730 | text=f"Success. File saved as: {output_path / output_file_name}. Voice ID generated: {generated_voice_id}",
731 | )
732 |
733 | except MinimaxAPIError as e:
734 | return TextContent(
735 | type="text",
736 | text=f"Failed to design voice: {str(e)}"
737 | )
738 |
739 | def main():
740 | print("Starting Minimax MCP server")
741 | """Run the Minimax MCP server"""
742 | mcp.run()
743 |
744 |
745 | if __name__ == "__main__":
746 | main()
747 |
```