MiniMax MCP JS

ドキュメント

• 中国語ドキュメント
• Python 版 - MiniMax MCP の公式 Python 実装

リリースノート

2025年7月22日

🔧 修正と改善

• TTS ツールの修正：text_to_audio ツールの languageBoost と subtitleEnable のパラメーター処理を修正しました
• API レスポンスの強化：TTS API が音声ファイルと字幕ファイルの両方を返せるようになり、より充実した音声テキスト変換を体験できます

2025年7月7日

🆕 新機能

• ボイスデザイン：新しい voice_design ツール。説明的なプロンプトから、プレビュー音声付きのカスタム音声を作成できます
• 動画の強化：高精細な画質と再生時間・解像度の制御に対応した MiniMax-Hailuo-02 モデルを追加しました

📈 ツールの強化

• voice_design - テキストによる説明からパーソナライズされた音声を生成します
• generate_video - MiniMax-Hailuo-02 に対応しました。再生時間は 6 秒／10 秒、解像度は 768P／1080P から選択できます

機能

• テキスト読み上げ（TTS）
• 画像生成
• 動画生成
• 音声クローニング
• ボイスデザイン
• 動的設定（環境変数とリクエストパラメーターの両方に対応）
• MCP プラットフォームでのホスティングに対応（ModelScope などの MCP プラットフォーム）

インストール

Smithery 経由でインストール

Smithery を使って、Claude Desktop に MiniMax MCP JS を自動でインストールするには：

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

手動でインストール

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

クイックスタート

MiniMax MCP JS は Model Context Protocol (MCP) の仕様を実装しており、MCP 対応クライアント（Claude AI など）と連携するサーバーとして使用できます。

MCP クライアントでのクイックスタート

1. MiniMax International Platform から API キーを取得します。
2. Node.js と npm がすでにインストールされていることを確認します
3. 重要：API HOST と KEY は地域によって異なります。必ず同じ地域のものを組み合わせてください。そうしないと、Invalid API key エラーが発生します。

地域	グローバル	中国本土
MINIMAX_API_KEY	MiniMax Global から取得	MiniMax から取得
MINIMAX_API_HOST	​https://api.minimaxi.chat（余分な 「i」 に注意）	​https://api.minimax.chat

MCP クライアントでの使用（推奨）

MCP クライアントを設定します：

Claude Desktop

Claude > Settings > Developer > Edit Config > claude_desktop_config.json に移動して、次の設定を追加します。

{
  "mcpServers": {
    "minimax-mcp-js": {
      "command": "npx",
      "args": [
        "-y",
        "minimax-mcp-js"
      ],
      "env": {
        "MINIMAX_API_HOST": "<https://api.minimaxi.chat|https://api.minimax.chat>",
        "MINIMAX_API_KEY": "<your-api-key-here>",
        "MINIMAX_MCP_BASE_PATH": "<local-output-dir-path, such as /User/xxx/Desktop>",
        "MINIMAX_RESOURCE_MODE": "<optional, [url|local], url is default, audio/image/video are downloaded locally or provided in URL format>"
      }
    }
  }
}

Cursor

Cursor → Preferences → Cursor Settings → MCP → Add new global MCP Server に移動して、上記の設定を追加します。

⚠️ 注意：Cursor で MiniMax MCP JS を使用する際に「No tools found」エラーが発生した場合は、Cursor を最新バージョンに更新してください。詳細については、このディスカッションスレッドをご覧ください。

これで完了です。MCP クライアントがこれらのツールを通じて MiniMax と連携できるようになります。

ローカル開発の場合：
ローカルで開発する際は、npm link を使用して変更をテストできます。

# In your project directory
npm link

その後、上記のように npx を使用するよう Claude Desktop または Cursor を設定します。これにより、リンクしたバージョンが自動的に使用されます。

⚠️ 注意：API キーはホストアドレスと一致させる必要があります。グローバル版と中国本土版では、異なるホストが使用されます。

• グローバルホスト：https://api.minimaxi.chat（「i」が余分に含まれていることに注意）
• 中国本土ホスト：https://api.minimaxi.chat

トランスポートモード

MiniMax MCP JS は、3 つのトランスポートモードをサポートしています。

機能	stdio（デフォルト）	REST	SSE
環境	ローカルのみ	ローカルまたはクラウドへのデプロイ	ローカルまたはクラウドへのデプロイ
通信	standard I/O 経由	HTTP requests 経由	server-sent events 経由
使用例	ローカル MCP クライアントとの連携	API サービス、言語間の呼び出し	サーバープッシュを必要とするアプリケーション
入力の制限	local files または URL リソースをサポート	クラウドにデプロイする場合は、URL 入力を推奨	クラウドにデプロイする場合は、URL 入力を推奨

設定

MiniMax-MCP-JS には、さまざまなユースケースに対応できる柔軟な設定方法が複数用意されています。設定の優先順位は、高いものから順に次のとおりです。

1. リクエストパラメーターによる設定（最優先）

プラットフォームのホスティング環境（ModelScope などの MCP プラットフォーム）では、リクエストパラメーターの meta.auth オブジェクトを使用して、リクエストごとに個別の設定を指定できます。

{
  "params": {
    "meta": {
      "auth": {
        "api_key": "your_api_key_here",
        "api_host": "<https://api.minimaxi.chat|https://api.minimaxi.chat>",
        "base_path": "/path/to/output",
        "resource_mode": "url"
      }
    }
  }
}

この方法により、リクエストごとに異なる API キーと設定を使用するマルチテナント運用が可能になります。

2. API による設定

他のプロジェクトでモジュールとして使用する場合は、startMiniMaxMCP 関数を通じて設定を渡せます。

import { startMiniMaxMCP } from 'minimax-mcp-js';

await startMiniMaxMCP({
  apiKey: 'your_api_key_here',
  apiHost: 'https://api.minimaxi.chat', // Global Host - https://api.minimaxi.chat, Mainland Host - https://api.minimax.chat
  basePath: '/path/to/output',
  resourceMode: 'url'
});

3. コマンドライン引数

1. CLI ツールをグローバルにインストールします。

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

2. CLI ツールとして使用する場合は、コマンドライン引数で設定を指定できます。

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

4. 環境変数（優先度が最も低い）

最も基本的な設定方法は、環境変数を使用する方法です。

# MiniMax API Key (required)
MINIMAX_API_KEY=your_api_key_here

# Base path for output files (optional, defaults to user's desktop)
MINIMAX_MCP_BASE_PATH=~/Desktop

# MiniMax API Host (optional, defaults to https://api.minimaxi.chat, Global Host - https://api.minimaxi.chat, Mainland Host - https://api.minimax.chat)
MINIMAX_API_HOST=https://api.minimaxi.chat

# Resource mode (optional, defaults to 'url')
# Options: 'url' (return URLs), 'local' (save files locally)
MINIMAX_RESOURCE_MODE=url

設定の優先順位

複数の設定方法を使用する場合、次の優先順位が適用されます（高いものから順）。

1. リクエスト単位の設定（各 API リクエストの meta.auth を使用）
2. コマンドライン引数
3. 環境変数
4. 設定ファイル
5. デフォルト値

この優先順位により、マルチテナント環境でリクエストごとの設定機能を維持しながら、さまざまなデプロイシナリオに柔軟に対応できます。

設定パラメーター

パラメーター	説明	デフォルト値
apiKey	MiniMax API キー	なし（必須）
apiHost	MiniMax API ホスト	グローバルホスト - https://api.minimaxi.chat、中国本土ホスト - https://api.minimax.chat
basePath	出力ファイルのベースパス	ユーザーのデスクトップ
resourceMode	リソースの処理モード。「url」または「local」	url

⚠️ 注意：API キーはホストアドレスと一致させる必要があります。グローバル版と中国本土版では、異なるホストが使用されます。

• グローバルホスト：https://api.minimaxi.chat（「i」が余分に含まれていることに注意）
• 中国本土ホスト：https://api.minimax.chat

使用例

⚠️ 警告：これらのツールを使用すると、料金が発生する場合があります。

1. 夜のニュースの一部を放送する

2. 音声をクローンする

3. 動画を生成する

4. 画像を生成する

5. 音声デザイン

利用可能なツール

テキストから音声へ

テキストを音声ファイルに変換します。

ツール名：text_to_audio

パラメーター：

• text：変換するテキスト（必須）
• model：モデルのバージョン。選択肢は 'speech-02-hd'、'speech-02-turbo'、'speech-01-hd'、'speech-01-turbo'、'speech-01-240228'、'speech-01-turbo-240228' で、デフォルトは 'speech-02-hd' です
• voiceId：音声 ID。デフォルトは 'male-qn-qingse' です
• speed：読み上げ速度。範囲は 0.5～2.0 で、デフォルトは 1.0 です
• vol：音量。範囲は 0.1～10.0 で、デフォルトは 1.0 です
• pitch：ピッチ。範囲は -12～12 で、デフォルトは 0 です
• emotion：感情。選択肢は 'happy'、'sad'、'angry'、'fearful'、'disgusted'、'surprised'、'neutral' で、デフォルトは 'happy' です。注：このパラメーターは 'speech-02-hd'、'speech-02-turbo'、'speech-01-turbo'、'speech-01-hd' モデルでのみ機能します
• format：音声形式。選択肢は 'mp3'、'pcm'、'flac'、'wav' で、デフォルトは 'mp3' です
• sampleRate：サンプルレート（Hz）。選択肢は 8000、16000、22050、24000、32000、44100 で、デフォルトは 32000 です
• bitrate：ビットレート（bps）。選択肢は 64000、96000、128000、160000、192000、224000、256000、320000 で、デフォルトは 128000 です
• channel：音声チャンネル数。選択肢は 1 または 2 で、デフォルトは 1 です
• languageBoost：指定した言語や方言の認識能力を高めます。 対応する値は次のとおりです： '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'。デフォルトは 'auto' です
• stream：ストリーミング出力を有効にします
• subtitleEnable：字幕サービスを有効にするかどうかを指定します。モデルは 'speech-01-turbo' または 'speech-01-hd' である必要があります。このパラメーターを指定しない場合、デフォルト値は false です
• outputDirectory：出力ファイルを保存するディレクトリ。outputDirectory は MINIMAX_MCP_BASE_PATH（または設定ファイルの basePath）からの相対パスです。最終的な保存先は ${basePath}/${outputDirectory} です。たとえば、MINIMAX_MCP_BASE_PATH=~/Desktop かつ outputDirectory=workspace の場合、出力は ~/Desktop/workspace/ に保存されます。（任意）
• outputFile：出力ファイルの保存先パス（任意。指定しない場合は自動生成されます）

音声を再生

音声ファイルを再生します。WAV 形式と MP3 形式に対応しています。動画には対応していません。

ツール名：play_audio

パラメーター：

• inputFilePath：再生する音声ファイルのパス（必須）
• isUrl：音声ファイルが URL かどうか。デフォルトは false です

音声をクローン

音声ファイルから声をクローンします。

ツール名：voice_clone

パラメーター：

• audioFile：音声ファイルのパス（必須）
• voiceId：音声 ID（必須）
• text：デモ音声用のテキスト（任意）
• outputDirectory：出力ファイルを保存するディレクトリ。outputDirectory は MINIMAX_MCP_BASE_PATH（または設定内の basePath）からの相対パスです。最終的な保存先は ${basePath}/${outputDirectory} です。たとえば、MINIMAX_MCP_BASE_PATH=~/Desktop かつ outputDirectory=workspace の場合、出力は ~/Desktop/workspace/ に保存されます。（任意）

テキストから画像を生成

テキストプロンプトに基づいて画像を生成します。

ツール名：text_to_image

パラメーター：

• prompt：画像の説明（必須）
• model：モデルのバージョン。デフォルトは 'image-01' です
• aspectRatio：アスペクト比。デフォルトは '1:1' です。選択肢は '1:1'、'16:9'、'4:3'、'3:2'、'2:3'、'3:4'、'9:16'、'21:9' です
• n：生成する画像の数。範囲は 1～9 で、デフォルトは 1 です
• promptOptimizer：プロンプトを最適化するかどうか。デフォルトは true です
• subjectReference：キャラクターの参照に使用するローカル画像ファイルのパス、または公開 URL（任意）
• outputDirectory：出力ファイルを保存するディレクトリ。outputDirectory は MINIMAX_MCP_BASE_PATH（または設定内の basePath）からの相対パスです。最終的な保存先は ${basePath}/${outputDirectory} です。たとえば、MINIMAX_MCP_BASE_PATH=~/Desktop かつ outputDirectory=workspace の場合、出力は ~/Desktop/workspace/ に保存されます。（任意）
• outputFile：出力ファイルの保存先パス（任意。指定しない場合は自動生成されます）
• asyncMode：非同期モードを使用するかどうか。デフォルトは False です。True の場合、動画生成タスクは非同期で送信され、レスポンスに task_id が返されます。タスクの状態を確認して結果を取得するには、query_video_generation ツールを使用してください。（任意）

動画を生成

テキストプロンプトに基づいて動画を生成します。

ツール名：generate_video

パラメーター：

• prompt：動画の説明（必須）
• model：モデルのバージョン。選択肢は 'T2V-01'、'T2V-01-Director'、'I2V-01'、'I2V-01-Director'、'I2V-01-live'、'S2V-01'、'MiniMax-Hailuo-02' で、デフォルトは 'MiniMax-Hailuo-02' です
• firstFrameImage：最初のフレーム画像のパス（任意）
• duration：動画の長さ。モデルは "MiniMax-Hailuo-02" である必要があります。値は 6 または 10 です。（任意）
• resolution：動画の解像度。モデルは "MiniMax-Hailuo-02" である必要があります。値は ["768P", "1080P"] の範囲です。（任意）
• outputDirectory：出力ファイルを保存するディレクトリ。outputDirectory は MINIMAX_MCP_BASE_PATH（または設定内の basePath）からの相対パスです。最終的な保存先は ${basePath}/${outputDirectory} です。たとえば、MINIMAX_MCP_BASE_PATH=~/Desktop かつ outputDirectory=workspace の場合、出力は ~/Desktop/workspace/ に保存されます。（任意）
• outputFile：出力ファイルの保存先パス（任意。指定しない場合は自動生成されます）
• asyncMode：非同期モードを使用するかどうか。デフォルトは False です。True の場合、動画生成タスクは非同期で送信され、レスポンスに task_id が返されます。タスクの状態を確認して結果を取得するには、query_video_generation ツールを使用してください。（任意）

動画生成ステータスを照会

動画生成タスクのステータスを照会します。

ツール名：query_video_generation

パラメーター：

• taskId：照会するタスク ID。async_mode が True の場合、generate_video ツールから返された task_id を指定してください。（必須）
• outputDirectory：出力ファイルを保存するディレクトリ。outputDirectory は MINIMAX_MCP_BASE_PATH（または設定内の basePath）からの相対パスです。最終的な保存先は ${basePath}/${outputDirectory} です。たとえば、MINIMAX_MCP_BASE_PATH=~/Desktop かつ outputDirectory=workspace の場合、出力は ~/Desktop/workspace/ に保存されます。（任意）

音声デザイン

説明プロンプトに基づいて音声を生成します。

ツール名：voice_design

パラメーター：

• prompt：音声の生成に使用するプロンプトです。（必須）
• previewText：音声をプレビューするテキストです。（必須）
• voiceId：使用する音声の ID です。例：「male-qn-qingse」／「audiobook_female_1」／「cute_boy」／「Charming_Lady」など。（任意）
• outputDirectory：出力ファイルの保存先ディレクトリです。outputDirectory は MINIMAX_MCP_BASE_PATH（または設定内の basePath）からの相対パスです。最終的な保存先は ${basePath}/${outputDirectory} です。たとえば、MINIMAX_MCP_BASE_PATH=~/Desktop で outputDirectory=workspace の場合、出力は ~/Desktop/workspace/ に保存されます。（任意）

よくある質問

1. generate_video を非同期モードで使用する方法

開始する前に完了ルールを定義してください。 または、IDE の設定（Cursor など）でこれらのルールを設定できます。

開発

セットアップ

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

# Install dependencies
pnpm install

ビルド

# Build the project
pnpm run build

実行

# Run the MCP server
pnpm start

ライセンス

MIT