Lm Studio MCP Server

🚀 LM Studio MCP 服務器

這是一個 MCP（模型上下文協議）服務器，它能讓 AI 助手對 LM Studio 模型進行控制。該服務器可通過 LM Studio API 實現遠程模型管理，包括列出、加載和卸載模型。

🚀 快速開始

本服務器允許通過 LM Studio API 進行遠程模型管理，包括列出、加載和卸載模型。使用前請確保滿足以下先決條件，並按照安裝和配置步驟操作。

✨ 主要特性

• 健康檢查：驗證與 LM Studio 的連接性。
• 列出已下載模型：查看 LM Studio 庫中所有可用的大語言模型（LLM）。
• 列出已加載模型：查看當前哪些模型已加載到內存中。
• 加載模型：使用可配置參數將模型加載到內存中。
• 卸載模型：從內存中移除特定的模型實例。
• 獲取模型信息：檢索已加載模型的詳細信息。

📦 安裝指南

# 克隆倉庫
git clone <repository-url>
cd lm-studio-mcp-server

# 安裝依賴
npm install

📚 詳細文檔

配置

服務器使用環境變量連接到 LM Studio：

使用方法

運行模式

開發模式（使用 tsx 執行 TypeScript）：

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 中所有已下載的大語言模型。

• 參數：無
• 返回：模型信息對象數組，包含：
  • 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