LMStudio-MCP

LMStudio-MCP

一个模型控制协议（MCP）服务，可让 Claude 通过 LM Studio 与本地运行的大模型通信。

概述

LMStudio-MCP 在 Claude（具备 MCP 功能）与本地运行的 LM Studio 实例之间搭建桥梁。这使 Claude 能够：

• 检查 LM Studio API 的运行状况
• 列出可用模型
• 获取当前加载的模型
• 使用本地模型生成聊天和原始文本补全
• 生成用于语义搜索和 RAG 的向量嵌入
• 通过响应 ID 保持有状态的多轮对话
• 使用固定的系统提示词启动并继续持久对话

这样，你便可以通过 Claude 的界面使用本地运行的模型，将 Claude 的能力与私有模型相结合。

前提条件

• Python 3.7+
• 已安装并在本地运行的 LM Studio，且已加载模型
• 可访问 MCP 的 Claude
• 所需的 Python 包（参见“安装”）

🚀 快速安装

一行安装（推荐）

curl -fsSL https://raw.githubusercontent.com/infinitimeless/LMStudio-MCP/main/install.sh | bash

手动安装方式

1. 本地 Python 安装

git clone https://github.com/infinitimeless/LMStudio-MCP.git
cd LMStudio-MCP
pip install requests "mcp[cli]" openai

2. Docker 安装

# Using pre-built image
docker run -it --network host ghcr.io/infinitimeless/lmstudio-mcp:latest

# Or build locally
git clone https://github.com/infinitimeless/LMStudio-MCP.git
cd LMStudio-MCP
docker build -t lmstudio-mcp .
docker run -it --network host lmstudio-mcp

3. Docker Compose

git clone https://github.com/infinitimeless/LMStudio-MCP.git
cd LMStudio-MCP
docker-compose up -d

详细部署说明请参阅 DOCKER.md。

⚙️ 配置

该桥接服务支持灵活配置，以适用于不同的部署场景：

• 默认：连接到 http://localhost:1234/v1
• 自定义主机：设置 LMSTUDIO_HOST 环境变量（例如 192.168.1.100）
• 自定义端口：设置 LMSTUDIO_PORT 环境变量（例如 5678）

示例：

export LMSTUDIO_HOST=192.168.1.100
export LMSTUDIO_PORT=5678
python lmstudio_bridge.py

📖 详细配置选项请参阅 CONFIGURATION.md

MCP 配置

快速设置

直接使用 GitHub（最简单）：

{
  "lmstudio-mcp": {
    "command": "uvx",
    "args": [
      "https://github.com/infinitimeless/LMStudio-MCP"
    ]
  }
}

使用本地安装：

{
  "lmstudio-mcp": {
    "command": "/bin/bash",
    "args": [
      "-c",
      "cd /path/to/LMStudio-MCP && source venv/bin/activate && python lmstudio_bridge.py"
    ]
  }
}

使用 Docker：

{
  "lmstudio-mcp-docker": {
    "command": "docker",
    "args": [
      "run",
      "-i",
      "--rm",
      "--network=host",
      "ghcr.io/infinitimeless/lmstudio-mcp:latest"
    ]
  }
}

完整的 MCP 配置说明请参阅 MCP_CONFIGURATION.md。

可选：MCP description 提示

你可以在 .mcp.json 条目中添加 description 字段，帮助 Claude 了解何时使用此服务以及需要注意什么。这对于提醒 Claude 注意版本要求尤其有用：

{
  "lmstudio-mcp": {
    "command": "...",
    "args": [...],
    "description": "Local LLM bridge via LM Studio. Use for private/offline inference, embeddings, and multi-turn conversations. start_conversation and continue_conversation require LM Studio v0.3.29+."
  }
}

🧠 LM Studio 系统提示词（推荐）

直接在 LM Studio 中设置系统提示词，可让本地模型在所有交互中保持一致的基础个性与行为，无需在每次 API 调用时都传入该提示词。

设置方法

1. 打开 LM Studio
2. 点击聊天面板顶部的模型名称
3. 找到 System Prompt 字段（可能位于 ⚙️ 齿轮图标或 Advanced settings 下）
4. 粘贴系统提示词并保存

此处设置的系统提示词适用于通过 API 发送的所有补全，包括通过此 MCP 桥接服务发送的补全。

系统提示词示例

通用助手——简洁直接：

You are a helpful, concise assistant. Answer directly without preamble like
"Sure!" or "Of course!". Never cut off mid-sentence — always finish your thought.

轻松随意的对话伙伴：

You are a regular person having a relaxed conversation with a friend.
Keep responses short and natural, like real chat. No bullet points or formal
language. You can invent fun details about your life and stay consistent with them.
Never cut off mid-sentence — always finish your thought.

本地编码助手：

You are an expert software engineer. Be concise and precise. When writing code,
always include brief inline comments. Prefer simple, readable solutions over
clever ones. Never cut off mid-sentence or mid-code block.

隐私优先的文档分析助手：

You are a careful document analyst. Summarise accurately and concisely.
Never invent information not present in the source material.
Always flag uncertainty explicitly.

💡 提示： 始终在系统提示词末尾加上“Never cut off mid-sentence — always finish your thought.”。无论 max_tokens 如何配置，这都可以防止响应被截断。

用法

1. 启动 LM Studio，并确保它在端口 1234（默认端口）上运行
2. 在 LM Studio 中设置系统提示词（见上文，推荐）
3. 在 LM Studio 中加载模型
4. 使用上述其中一种配置配置 Claude MCP
5. 根据提示在 Claude 中连接到 MCP 服务

可用工具

该桥接服务提供以下 9 个工具：

工具	描述
health_check()	验证是否可以访问 LM Studio API
list_models()	获取 LM Studio 中所有可用模型的列表
get_current_model()	确认当前已加载的模型
chat_completion(prompt, system_prompt, temperature, max_tokens)	使用本地模型生成聊天回复
text_completion(prompt, temperature, max_tokens, stop_sequences)	生成原始文本／代码补全——速度更快，无聊天格式开销
generate_embeddings(text, model)	生成向量嵌入，用于语义搜索和 RAG 工作流
create_response(input_text, previous_response_id, reasoning_effort, stream, model)	通过响应 ID 进行有状态对话——需要 LM Studio v0.3.29+
start_conversation(system_prompt, first_message, temperature, max_tokens, model)	启动多轮会话并保留系统提示词——返回 response_id
continue_conversation(response_id, message, temperature, max_tokens, model)	继续通过 start_conversation 启动的会话——自动保留上下文

多轮对话工作流

使用本地模型进行持久对话的推荐方式：

1. start_conversation(
     system_prompt="You are a friend at a bar, keep it casual and fun.",
     first_message="Hey! How's it going?"
   )
   → { response_id: "resp_abc...", message: "Hey! Not bad, just unwinding..." }

2. continue_conversation(
     response_id="resp_abc...",
     message="Work's been insane this week."
   )
   → { response_id: "resp_def...", message: "Ugh, tell me about it..." }

3. continue_conversation(
     response_id="resp_def...",
     message="If you could go anywhere tomorrow, where would you go?"
   )
   → { response_id: "resp_ghi...", message: "Honestly? Northern Portugal..." }

系统提示词会在整个会话期间保持不变——无需在每轮对话中重新发送。 需要 LM Studio v0.3.29+。

部署选项

该项目支持多种部署方式：

方式	使用场景	优点	缺点
本地 Python	开发、简单设置	快速、可直接控制	需要配置 Python
Docker	隔离环境	整洁、可移植	需要 Docker
Docker Compose	生产部署	易于管理	设置较复杂
Kubernetes	企业／大规模部署	高度可扩展	配置复杂
GitHub 直接部署	零配置	无需本地安装	需要互联网连接

已知限制

• 某些模型（例如 phi-3.5-mini-instruct_uncensored）可能存在兼容性问题
• 该桥接服务目前仅使用 LM Studio 的 OpenAI 兼容 API 端点
• 模型回复能力受本地已加载模型的能力限制
• create_response、start_conversation 和 continue_conversation 需要 LM Studio v0.3.29+
• generate_embeddings 需要专用的嵌入模型（例如 text-embedding-nomic-embed-text-v1.5）

故障排除

API 连接问题

如果 Claude 在尝试连接 LM Studio 时报告 404 错误：

• 确保 LM Studio 正在运行且已加载模型
• 检查 LM Studio 服务是否运行在端口 1234 上
• 确认防火墙未阻止连接
• 如果问题仍然存在，请尝试在 API URL 中使用 "127.0.0.1" 替代 "localhost"

模型兼容性

如果某些模型无法正常工作：

• 某些模型可能不完全支持 OpenAI 聊天补全 API 格式
• 对于有问题的模型，请尝试使用不同的参数值（temperature、max_tokens）
• 如果问题仍然存在，请考虑切换到兼容性更好的模型

如需详细的故障排除帮助，请参阅 TROUBLESHOOTING.md。

🐳 Docker 与容器化

该项目提供全面的 Docker 支持：

• 多架构镜像（AMD64、ARM64／Apple Silicon）
• 通过 GitHub Actions 自动构建
• GitHub Container Registry 上提供 预构建镜像
• 使用 Docker Compose 轻松部署
• 面向生产部署的 Kubernetes 清单

完整的容器化文档请参阅 DOCKER.md。

贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解相关指南。

许可证

MIT

致谢

该项目最初以 “Claude-LMStudio-Bridge_V2” 的名称开发，之后更名并以开源形式发布，名称为 “LMStudio-MCP”。

社区项目

想要更高级的功能？来看看社区构建的增强版：

• lmstudio-bridge-enhanced 由 @ahmedibrahim085 开发 — 在本项目基础上构建的强大扩展，新增了自主 Agent 循环、37 个工具、动态 MCP 发现、多模型路由、视觉支持等诸多功能。

---

🌟 如果这个项目对你有帮助，请考虑为它点亮一颗星！