Unsloth MCP Server

Unsloth MCP サーバー

Unsloth 用の MCP サーバーです。LLM のファインチューニングをメモリ使用量 80％削減で 2 倍高速化するライブラリです。

Unsloth とは？

Unsloth は、大規模言語モデルのファインチューニング効率を大幅に向上させるライブラリです。

• 速度：標準的な方法と比べて、ファインチューニングが 2 倍高速です
• メモリ：VRAM の使用量を 80％削減し、一般向け GPU でより大きなモデルをファインチューニングできます
• コンテキスト長：最大 13 倍長いコンテキスト長に対応します（例：80GB GPU での Llama 3.3 では 89K トークン）
• 精度：モデルの品質や性能は低下しません

Unsloth は、OpenAI の Triton 言語で記述されたカスタム CUDA カーネル、最適化された誤差逆伝播法、動的な 4 ビット量子化によって、これらの改善を実現しています。

機能

• Llama、Mistral、Phi、Gemma などのモデルのファインチューニングを最適化
• 効率的なトレーニングのための 4 ビット量子化
• 拡張コンテキスト長に対応
• モデルの読み込み、ファインチューニング、推論のためのシンプルな API
• さまざまな形式（GGUF、Hugging Face など）にエクスポート

インストール

**現在の状態：**以下の手順でソースからインストールしてください。パッケージは npm に対応する準備ができています（name、bin、server.json レジストリマニフェストが設定済み）が、まだ公開されていません。次のセクションにある npx ベースの設定は、npm への公開後にのみ動作します。

1. ファインチューニングを実行するマシンに Unsloth をインストールします：pip install unsloth

2. ソースからサーバーをビルドします：

   git clone https://github.com/OtotaO/unsloth-mcp-server.git
   cd unsloth-mcp-server
   npm install
   npm run build
   

3. MCP クライアント（Claude Desktop、Claude Code、Cline、Cursor など）で、ビルドしたエントリーポイントを指定します：

   {
     "mcpServers": {
       "unsloth": {
         "command": "node",
         "args": ["/path/to/unsloth-mcp-server/build/index.js"],
         "env": { "HUGGINGFACE_TOKEN": "your_token_here" }
       }
     }
   }
   

   HUGGINGFACE_TOKEN は任意です（ゲート付き／プライベートモデルにのみ必要です）。使用しない場合は env ブロックを省略してください。

npm 公開後（予定）

unsloth-mcp-server として npm に公開された後は、同じクライアントから npx を使って stdio 経由で実行でき、リポジトリのクローンやビルドは不要になります：

{
  "mcpServers": {
    "unsloth": {
      "command": "npx",
      "args": ["-y", "unsloth-mcp-server"],
      "env": { "HUGGINGFACE_TOKEN": "your_token_here" }
    }
  }
}

Claude Code の場合：claude mcp add unsloth -- npx -y unsloth-mcp-server

利用可能なツール

check_installation

Unsloth がシステムに正しくインストールされているか確認します。

パラメーター：なし

例：

const result = await use_mcp_tool({
  server_name: "unsloth",
  tool_name: "check_installation",
  arguments: {}
});

list_supported_models

Llama、Mistral、Phi、Gemma の各種モデルを含む、Unsloth がサポートするすべてのモデルの一覧を取得します。

パラメーター：なし

例：

const result = await use_mcp_tool({
  server_name: "unsloth",
  tool_name: "list_supported_models",
  arguments: {}
});

load_model

Unsloth の最適化を適用して、推論とファインチューニングを高速化しながら事前学習済みモデルを読み込みます。

パラメーター：

• model_name（必須）：読み込むモデルの名前（例："unsloth/Llama-3.2-1B"）
• max_seq_length（任意）：モデルの最大シーケンス長（デフォルト：2048）
• load_in_4bit（任意）：モデルを 4 ビット量子化で読み込むかどうか（デフォルト：true）
• use_gradient_checkpointing（任意）：メモリを節約するために勾配チェックポイントを使用するかどうか（デフォルト：true）

例：

const result = await use_mcp_tool({
  server_name: "unsloth",
  tool_name: "load_model",
  arguments: {
    model_name: "unsloth/Llama-3.2-1B",
    max_seq_length: 4096,
    load_in_4bit: true
  }
});

finetune_model

LoRA／QLoRA の手法を使い、Unsloth の最適化を適用してモデルをファインチューニングします。

パラメーター：

• model_name（必須）：ファインチューニングするモデルの名前
• dataset_name（必須）：ファインチューニングに使用するデータセットの名前
• output_dir（必須）：ファインチューニング済みモデルの保存先ディレクトリ
• max_seq_length（任意）：トレーニングの最大シーケンス長（デフォルト：2048）
• lora_rank（任意）：LoRA ファインチューニングのランク（デフォルト：16）
• lora_alpha（任意）：LoRA ファインチューニングのアルファ値（デフォルト：16）
• batch_size（任意）：トレーニングのバッチサイズ（デフォルト：2）
• gradient_accumulation_steps（任意）：勾配累積のステップ数（デフォルト：4）
• learning_rate（任意）：トレーニングの学習率（デフォルト：2e-4）
• max_steps（任意）：トレーニングの最大ステップ数（デフォルト：100）
• dataset_text_field（任意）：テキストを含むデータセット内のフィールド（デフォルト：'text'）
• load_in_4bit（任意）：4 ビット量子化を使用するかどうか（デフォルト：true）

例：

const result = await use_mcp_tool({
  server_name: "unsloth",
  tool_name: "finetune_model",
  arguments: {
    model_name: "unsloth/Llama-3.2-1B",
    dataset_name: "tatsu-lab/alpaca",
    output_dir: "./fine-tuned-model",
    max_steps: 100,
    batch_size: 2,
    learning_rate: 2e-4
  }
});

generate_text

ファインチューニング済みの Unsloth モデルを使用してテキストを生成します。

パラメーター:

• model_path（必須）：ファインチューニング済みモデルへのパス
• prompt（必須）：テキスト生成用のプロンプト
• max_new_tokens（任意）：生成するトークンの最大数（デフォルト：256）
• temperature（任意）：テキスト生成時の温度（デフォルト：0.7）
• top_p（任意）：テキスト生成時の top-p（デフォルト：0.9）

例:

const result = await use_mcp_tool({
  server_name: "unsloth",
  tool_name: "generate_text",
  arguments: {
    model_path: "./fine-tuned-model",
    prompt: "Write a short story about a robot learning to paint:",
    max_new_tokens: 512,
    temperature: 0.8
  }
});

export_model

ファインチューニング済みの Unsloth モデルを、デプロイ用にさまざまな形式でエクスポートします。

パラメーター:

• model_path（必須）：ファインチューニング済みモデルへのパス
• export_format（必須）：エクスポートする形式（gguf、ollama、vllm、huggingface）
• output_path（必須）：エクスポートしたモデルの保存先パス
• quantization_bits（任意）：量子化のビット数（GGUF エクスポート用）（デフォルト：4）

例:

const result = await use_mcp_tool({
  server_name: "unsloth",
  tool_name: "export_model",
  arguments: {
    model_path: "./fine-tuned-model",
    export_format: "gguf",
    output_path: "./exported-model.gguf",
    quantization_bits: 4
  }
});

高度な使い方

カスタムデータセット

カスタムデータセットは、適切な形式に整えて Hugging Face でホストするか、ローカルパスを指定して使用できます。

const result = await use_mcp_tool({
  server_name: "unsloth",
  tool_name: "finetune_model",
  arguments: {
    model_name: "unsloth/Llama-3.2-1B",
    dataset_name: "json",
    data_files: {"train": "path/to/your/data.json"},
    output_dir: "./fine-tuned-model"
  }
});

メモリの最適化

限られたハードウェアで大規模モデルを使用する場合：

• バッチサイズを小さくし、勾配累積ステップ数を増やします
• 4-bit 量子化を使用します
• 勾配チェックポイントを有効にします
• 可能であればシーケンス長を短くします

トラブルシューティング

よくある問題

1. CUDA のメモリ不足：バッチサイズを小さくするか、4-bit 量子化を使用するか、より小さなモデルを試してください
2. インポートエラー：torch、transformers、unsloth の正しいバージョンがインストールされていることを確認してください
3. モデルが見つからない：サポートされているモデル名を使用していること、またはプライベートモデルへのアクセス権があることを確認してください

バージョンの互換性

• Python：3.10、3.11、または 3.12（3.13 は不可）
• CUDA：11.8 または 12.1 以降を推奨
• PyTorch：2.0 以降を推奨

パフォーマンスベンチマーク

モデル	VRAM	Unsloth の速度	VRAM の削減率	コンテキスト長
Llama 3.3 (70B)	80GB	2 倍高速	>75%	13 倍長い
Llama 3.1 (8B)	80GB	2 倍高速	>70%	12 倍長い
Mistral v0.3 (7B)	80GB	2.2 倍高速	75% 削減	-

要件

• Python 3.10-3.12
• CUDA 対応の NVIDIA GPU（推奨）
• Node.js と npm

ライセンス

Apache-2.0