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