Lm Studio MCP Server

🚀 LM Studio MCP Server

AIアシスタントがLM Studioのモデルを制御するためのMCP（Model Context Protocol）サーバーです。このサーバーは、LM Studio APIを通じて、モデルの一覧表示、読み込み、アンロードなどのリモートモデル管理を可能にします。

✨ 主な機能

• ヘルスチェック：LM Studioへの接続を確認します。
• ダウンロード済みモデルの一覧表示：LM Studioライブラリ内のすべてのLLMモデルを表示します。
• 読み込まれているモデルの一覧表示：現在メモリに読み込まれているモデルを表示します。
• モデルの読み込み：設定可能なパラメータでモデルをメモリに読み込みます。
• モデルのアンロード：特定のモデルインスタンスをメモリから削除します。
• モデル情報の取得：読み込まれているモデルの詳細情報を取得します。

📦 インストール

前提条件

• Node.js 18.0.0以上
• ローカルサーバーが有効になっているLM Studio

# リポジトリをクローン
git clone <repository-url>
cd lm-studio-mcp-server

# 依存関係をインストール
npm install

設定

サーバーは環境変数を使用してLM Studioに接続します。

💻 使用例

実行モード

開発モード（TypeScriptの実行にtsxを使用）：

npm start
# またはファイル監視を有効にする場合
npm run dev

本番モード（コンパイルされたJavaScriptを使用）：

npm run build
npm run start:prod

Docker：

# 公開されているイメージを取得
docker pull portertech/lm-studio-mcp-server:latest

# 実行（ホストマシン上のLM Studioに接続）
docker run -i --rm portertech/lm-studio-mcp-server:latest

# カスタムのLM Studioホストで実行
docker run -i --rm \
  -e LMSTUDIO_HOST=192.168.1.100 \
  -e LMSTUDIO_PORT=1234 \
  portertech/lm-studio-mcp-server:latest

MCPクライアントの設定

Claude

claude_desktop_config.jsonに追加します。

npxを使用する場合（インストールされたパッケージに推奨）：

{
  "mcpServers": {
    "lmstudio": {
      "command": "npx",
      "args": ["@portertech/lm-studio-mcp-server"],
      "env": {
        "LMSTUDIO_HOST": "127.0.0.1",
        "LMSTUDIO_PORT": "1234"
      }
    }
  }
}

ローカル開発を使用する場合：

{
  "mcpServers": {
    "lmstudio": {
      "command": "npx",
      "args": ["tsx", "/path/to/lm-studio-mcp-server/src/index.ts"],
      "env": {
        "LMSTUDIO_HOST": "127.0.0.1",
        "LMSTUDIO_PORT": "1234"
      }
    }
  }
}

Dockerを使用する場合：

{
  "mcpServers": {
    "lmstudio": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "LMSTUDIO_HOST=127.0.0.1",
        "-e",
        "LMSTUDIO_PORT=1234",
        "portertech/lm-studio-mcp-server:latest"
      ]
    }
  }
}

⚠️ 重要提示

macOS/WindowsのDockerからホストマシン上のLM Studioに接続する場合は、LMSTUDIO_HOST=host.docker.internalを使用してください。

利用可能なツール

すべてのツールは一貫したレスポンスエンベロープを返します。

{
  success: boolean;
  message: string;
  data?: T;           // 成功時に存在
  error?: {           // 失敗時に存在
    code: string;
    message: string;
  };
}

エラーコード

health_check

LM Studioサーバーへの接続を確認します。

• パラメータ：なし
• 戻り値：接続ステータスとベースURL

list_models

LM Studioで利用可能なすべてのダウンロード済みLLMモデルを一覧表示します。

• パラメータ：なし
• 戻り値：以下の情報を持つモデル情報オブジェクトの配列
  • modelKey：読み込み用のモデル識別子
  • path：モデルへの相対パス
  • displayName：人間が読みやすいモデル名
  • sizeBytes：バイト単位のサイズ
  • architecture：モデルアーキテクチャ（利用可能な場合）
  • quantization：量子化タイプ（利用可能な場合）

list_loaded_models

現在メモリに読み込まれているすべてのモデルを一覧表示します。

• パラメータ：なし
• 戻り値：以下の情報を持つ読み込まれたモデル情報の配列
  • identifier：インスタンス識別子
  • modelKey：モデルキー
  • path：モデルパス
  • displayName：人間が読みやすい名前
  • sizeBytes：バイト単位のサイズ
  • vision：モデルがビジョンをサポートしているかどうか
  • trainedForToolUse：モデルがツール使用のためにトレーニングされたかどうか

load_model

モデルをメモリに読み込みます。

• パラメータ
  • model（必須）：読み込むモデルキー（例：llama-3.2-3b-instruct）
  • identifier（オプション）：読み込まれたインスタンスのカスタム識別子
  • contextLength（オプション）：トークン単位のコンテキストウィンドウサイズ（最小：1）
  • evalBatchSize（オプション）：トークン処理のバッチサイズ（最小：1）
• 戻り値：読み込まれたモデルの詳細（識別子、モデルキー、パス）を含む成功ステータス

unload_model

モデルをメモリからアンロードします。

• パラメータ
  • identifier（必須）：アンロードする読み込まれたモデルの識別子
• 戻り値：成功ステータス

get_model_info

読み込まれたモデルの詳細情報を取得します。

• パラメータ
  • identifier（必須）：読み込まれたモデルの識別子
• 戻り値：識別子、モデルキー、パス、表示名、サイズ（バイト）、コンテキスト長を含むモデルの詳細

📚 ドキュメント

開発

# プロジェクトをビルド
npm run build

# 自動リロードで開発モードで実行
npm run dev

# 型チェック（出力なし）
npm run typecheck

# テストを実行
npm test

# リント
npm run lint

# フォーマット
npm run format:check
npm run format

リリースプロセス

プロジェクトには自動化されたリリース用のmake releaseコマンドが含まれています。

# 新しいリリースを作成（CIを実行、バージョンを設定、コミット、タグ付け、npmとDocker Hubに公開）
make release VERSION=<version>

# 例:
make release VERSION=1.0.5

これは完全なリリースパイプラインを実行します。

1. CIチェック（リント、型チェック、テスト）
2. package.jsonのバージョンを設定
3. バージョンの更新をコミット
4. 注釈付きのgitタグ（v<version>）を作成
5. npmに公開
6. DockerイメージをビルドしてDocker Hubにプッシュ

プロジェクト構造

src/
├── index.ts              # MCPサーバーのエントリーポイント
├── client.ts             # LM Studioクライアントラッパー
├── types.ts              # 共有型と結果ヘルパー
└── tools/
    ├── index.ts          # ツールのエクスポート
    ├── health-check.ts   # ヘルスチェックツール
    ├── list-models.ts    # ダウンロード済みモデルを一覧表示
    ├── list-loaded-models.ts
    ├── load-model.ts
    ├── unload-model.ts
    └── get-model-info.ts

アーキテクチャ

• 一貫した結果：すべてのツールは同じToolResult<T>エンベロープを返します。
• 安全なラッパー：ツールハンドラーは例外をキャッチし、エラーペイロードを返すようにラップされています。
• 遅延構成：環境変数はモジュールの読み込み時ではなく実行時に読み取られます。
• シングルトンクライアント：単一のLM Studioクライアントインスタンスが再利用されます。

📄 ライセンス

ISC