MCP-LLM-Studio：让 Claude Code 无缝调用本地大模型的桥梁

一个 MCP 服务器项目，让 Claude Code 能够直接管理本地 LM Studio 实例中的模型，支持加载/卸载、推理、多轮对话和嵌入等完整功能。

背景：本地大模型与 Claude Code 的鸿沟\n\nLM Studio 是目前最流行的本地大模型运行工具之一，它让用户能够在自己的机器上运行 Llama、Qwen、Gemma 等开源模型。然而，Claude Code 作为 Anthropic 推出的命令行 AI 助手，默认并不支持与 LM Studio 直接通信。\n\n这意味着用户需要在两个环境之间手动切换：用 Claude Code 进行代码理解和任务规划，再切换到 LM Studio 进行本地模型推理。这种割裂的工作流大大降低了效率。\n\n## 项目概述：一座双向桥梁\n\nmcp-llm-studio 是一个基于 Model Context Protocol (MCP) 的服务器项目，它填补了上述鸿沟。通过这个项目，Claude Code 获得了与本地 LM Studio 实例对话的能力，用户可以用自然语言指令让 Claude 直接操控本地模型。\n\n项目的核心设计哲学是"让 Claude 自己编排"。用户只需说出类似"加载 qwen/qwen3.5-9b，让它总结这份日志，然后卸载模型"这样的指令，Claude 会自动调用相应工具完成整个流程。\n\n## 技术架构：双 API 混合策略\n\n该项目采用了一种巧妙的混合 API 策略来最大化功能覆盖：\n\nLM Studio 原生 REST API (/api/v1/*) 用于：\n- 模型生命周期管理（加载、卸载、下载）\n- 单轮推理（支持 reasoning 参数和详细统计）\n\nOpenAI 兼容 API (/v1/*) 用于：\n- 多轮对话（需要 SQLite 持久化历史，因为原生 chat 端点无法回播助手消息）\n- 文本嵌入（embeddings）\n\n这种设计充分利用了两种 API 的优势，既获得了原生 API 的 reasoning 控制和性能统计，又通过 OpenAI 兼容 API 实现了有状态的多轮对话。\n\n## 七大核心工具详解\n\n### 模型管理三件套\n\n1. model_list：列出当前已加载的模型\n2. model_load：将模型载入显存，支持配置上下文长度、GPU 卸载、Flash Attention 等参数，同步执行最长等待 5 分钟\n3. model_unload：从显存中卸载指定模型\n4. model_download：从 LM Studio 目录或 HuggingFace 直接下载模型，异步轮询进度\n\n### 推理与对话工具\n\n5. ask：单轮推理工具，通过原生 API 调用。支持 reasoning 参数（off/low/medium/high/on），返回生成文本、推理过程和详细统计（token/秒、首 token 时间、token 计数）\n\n6. chat：多轮对话工具，通过 OpenAI 兼容 API 调用。使用 SQLite 持久化会话历史，支持会话重置、草稿模型（推测解码）和自动过期清理\n\n7. embed：文本嵌入工具，支持单条或多条文本批量嵌入\n\n## 使用场景示例\n\n### 场景一：日志分析\n用户："用 google/gemma-3-4b 把这段日志总结成一句话"\n\nClaude 自动调用：\n\nask(model: \"google/gemma-3-4b\", prompt: \"...\", reasoning: \"off\")\n\n\n返回："日志显示在 14:02 至 14:06 之间，来自 10.0.0.4 的地址发生了 12 次认证失败。"\n\n### 场景二：代码重构规划\n用户："启动一个名为 'refactor-plan' 的会话，系统提示设为'你是一位资深 TypeScript 工程师'，然后问它我应该修改哪些文件"\n\nClaude 自动调用：\n\nchat(session_id: \"refactor-plan\", action: \"send\", model: \"...\", system: \"...\", message: \"...\")\n\n\n返回具体的文件修改建议列表。\n\n## 安全与配置考量\n\n项目在安全方面做了细致考虑：\n\n- SQLite 会话数据库 (MCP_SESSIONS_DB) 存储所有对话历史，包括系统提示。建议将其放在 $HOME 目录下，避免使用共享或全局可读的存储路径\n- API 密钥支持：可通过 LM_STUDIO_API_KEY 配置可选的 Bearer Token 认证\n- 灵活部署：支持通过 npx 直接运行，也支持从源码构建\n\n## 安装与配置\n\n最简单的安装方式（无需克隆或构建）：\n\nbash\nclaude mcp add llm-studio \\\n -e LM_STUDIO_URL=http://localhost:1234 \\\n -- npx -y mcp-llm-studio\n\n\n从源码运行：\n\nbash\ngit clone https://github.com/mecha1610/mcp-llm-studio.git\ncd mcp-llm-studio\nnpm install\nnpm run build\n\nclaude mcp add llm-studio \\\n -e LM_STUDIO_URL=http://localhost:1234 \\\n -- node \"$(pwd)/dist/server.js\"\n\n\n## 技术实现亮点\n\n项目采用 TypeScript 开发，使用 Vitest 进行单元测试，测试通过 mock fetch 和内存 SQLite 实现零副作用。CI 流程在每次推送时自动运行构建和测试。\n\n代码结构清晰，七个工具分别位于 src/tools/ 目录下，每个工具都有对应的单元测试。主服务器文件 server.ts 负责 MCP 组装和工具注册。\n\n## 结语：本地 AI 工作流的新范式\n\nmcp-llm-studio 代表了 AI 工具集成的新方向：不是让开发者学习复杂的 API，而是通过标准化协议（MCP）让不同工具自然协作。对于需要兼顾代码能力和本地模型隐私/成本优势的用户，这个项目提供了一条优雅的解决路径。

背景：本地大模型与 Claude Code 的鸿沟\n\nLM Studio 是目前最流行的本地大模型运行工具之一，它让用户能够在自己的机器上运行 Llama、Qwen、Gemma 等开源模型。然而，Claude Code 作为 Anthropic 推出的命令行 AI 助手，默认并不支持与 LM Studio 直接通信。\n\n这意味着用户需要在两个环境之间手动切换：用 Claude Code 进行代码理解和任务规划，再切换到 LM Studio 进行本地模型推理。这种割裂的工作流大大降低了效率。\n\n项目概述：一座双向桥梁\n\nmcp-llm-studio 是一个基于 Model Context Protocol (MCP) 的服务器项目，它填补了上述鸿沟。通过这个项目，Claude Code 获得了与本地 LM Studio 实例对话的能力，用户可以用自然语言指令让 Claude 直接操控本地模型。\n\n项目的核心设计哲学是"让 Claude 自己编排"。用户只需说出类似"加载 qwen/qwen3.5-9b，让它总结这份日志，然后卸载模型"这样的指令，Claude 会自动调用相应工具完成整个流程。\n\n技术架构：双 API 混合策略\n\n该项目采用了一种巧妙的混合 API 策略来最大化功能覆盖：\n\nLM Studio 原生 REST API (/api/v1/*) 用于：\n- 模型生命周期管理（加载、卸载、下载）\n- 单轮推理（支持 reasoning 参数和详细统计）\n\nOpenAI 兼容 API (/v1/*) 用于：\n- 多轮对话（需要 SQLite 持久化历史，因为原生 chat 端点无法回播助手消息）\n- 文本嵌入（embeddings）\n\n这种设计充分利用了两种 API 的优势，既获得了原生 API 的 reasoning 控制和性能统计，又通过 OpenAI 兼容 API 实现了有状态的多轮对话。\n\n七大核心工具详解\n\n模型管理三件套\n\n1. model_list：列出当前已加载的模型\n2. model_load：将模型载入显存，支持配置上下文长度、GPU 卸载、Flash Attention 等参数，同步执行最长等待 5 分钟\n3. model_unload：从显存中卸载指定模型\n4. model_download：从 LM Studio 目录或 HuggingFace 直接下载模型，异步轮询进度\n\n推理与对话工具\n\n5. ask：单轮推理工具，通过原生 API 调用。支持 reasoning 参数（off/low/medium/high/on），返回生成文本、推理过程和详细统计（token/秒、首 token 时间、token 计数）\n\n6. chat：多轮对话工具，通过 OpenAI 兼容 API 调用。使用 SQLite 持久化会话历史，支持会话重置、草稿模型（推测解码）和自动过期清理\n\n7. embed：文本嵌入工具，支持单条或多条文本批量嵌入\n\n使用场景示例\n\n场景一：日志分析\n用户："用 google/gemma-3-4b 把这段日志总结成一句话"\n\nClaude 自动调用：\n\nask(model: \"google/gemma-3-4b\", prompt: \"...\", reasoning: \"off\")\n\n\n返回："日志显示在 14:02 至 14:06 之间，来自 10.0.0.4 的地址发生了 12 次认证失败。"\n\n场景二：代码重构规划\n用户："启动一个名为 'refactor-plan' 的会话，系统提示设为'你是一位资深 TypeScript 工程师'，然后问它我应该修改哪些文件"\n\nClaude 自动调用：\n\nchat(session_id: \"refactor-plan\", action: \"send\", model: \"...\", system: \"...\", message: \"...\")\n\n\n返回具体的文件修改建议列表。\n\n安全与配置考量\n\n项目在安全方面做了细致考虑：\n\n- SQLite 会话数据库 (MCP_SESSIONS_DB) 存储所有对话历史，包括系统提示。建议将其放在 $HOME 目录下，避免使用共享或全局可读的存储路径\n- API 密钥支持：可通过 LM_STUDIO_API_KEY 配置可选的 Bearer Token 认证\n- 灵活部署：支持通过 npx 直接运行，也支持从源码构建\n\n安装与配置\n\n最简单的安装方式（无需克隆或构建）：\n\nbash\nclaude mcp add llm-studio \\\n -e LM_STUDIO_URL=http://localhost:1234 \\\n -- npx -y mcp-llm-studio\n\n\n从源码运行：\n\nbash\ngit clone https://github.com/mecha1610/mcp-llm-studio.git\ncd mcp-llm-studio\nnpm install\nnpm run build\n\nclaude mcp add llm-studio \\\n -e LM_STUDIO_URL=http://localhost:1234 \\\n -- node \"$(pwd)/dist/server.js\"\n\n\n技术实现亮点\n\n项目采用 TypeScript 开发，使用 Vitest 进行单元测试，测试通过 mock fetch 和内存 SQLite 实现零副作用。CI 流程在每次推送时自动运行构建和测试。\n\n代码结构清晰，七个工具分别位于 src/tools/ 目录下，每个工具都有对应的单元测试。主服务器文件 server.ts 负责 MCP 组装和工具注册。\n\n结语：本地 AI 工作流的新范式\n\nmcp-llm-studio 代表了 AI 工具集成的新方向：不是让开发者学习复杂的 API，而是通过标准化协议（MCP）让不同工具自然协作。对于需要兼顾代码能力和本地模型隐私/成本优势的用户，这个项目提供了一条优雅的解决路径。