内容
# LMStudio-MCP
一款允许 Claude 通过 LM Studio 在本地运行 LLM 模型的模型控制协议（MCP）服务器。
<img width="1881" alt="Screenshot 2025-03-22 at 16 50 53" src="https://github.com/user-attachments/assets/c203513b-28db-4be5-8c61-ebb8a24404ce" />
## 概述
LMStudio-MCP 在 Claude（具有 MCP 功能）和本地运行的 LM Studio 实例之间建立了一座桥梁。这使得 Claude 能够：
- 检查 LM Studio API 的健康状况
- 列出可用的模型
- 获取当前加载的模型
- 使用本地模型生成补全
这使得您能够通过 Claude 的界面利用您自己的本地运行模型，结合 Claude 的功能和您的私有模型。
## 前提条件
- Python 3.7+
- [LM Studio](https://lmstudio.ai/) 已安装并在本地运行，加载了一个模型
- 具有 MCP 访问权限的 Claude
- 所需的 Python 包（参见安装）
## 🚀 快速安装
### 一键安装（推荐）
```bash
curl -fsSL https://raw.githubusercontent.com/infinitimeless/LMStudio-MCP/main/install.sh | bash
```
### 手动安装方法
#### 1. 本地 Python 安装
```bash
git clone https://github.com/infinitimeless/LMStudio-MCP.git
cd LMStudio-MCP
pip install requests "mcp[cli]" openai
```
#### 2. Docker 安装
```bash
# 使用预构建的镜像
docker run -it --network host ghcr.io/infinitimeless/lmstudio-mcp:latest
# 或本地构建
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
```bash
git clone https://github.com/infinitimeless/LMStudio-MCP.git
cd LMStudio-MCP
docker-compose up -d
```
有关详细的部署说明，请参阅 [DOCKER.md](DOCKER.md)。
## MCP 配置
### 快速设置
**直接使用 GitHub（最简单）**：
```json
{
"lmstudio-mcp": {
"command": "uvx",
"args": [
"https://github.com/infinitimeless/LMStudio-MCP"
]
}
}
```
**使用本地安装**：
```json
{
"lmstudio-mcp": {
"command": "/bin/bash",
"args": [
"-c",
"cd /path/to/LMStudio-MCP && source venv/bin/activate && python lmstudio_bridge.py"
]
}
}
```
**使用 Docker**：
```json
{
"lmstudio-mcp-docker": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--network=host",
"ghcr.io/infinitimeless/lmstudio-mcp:latest"
]
}
}
```
有关完整的 MCP 配置说明，请参阅 [MCP_CONFIGURATION.md](MCP_CONFIGURATION.md)。
## 使用方法
1. **启动 LM Studio** 并确保它运行在端口 1234（默认）
2. **在 LM Studio 中加载模型**
3. **使用上述配置之一配置 Claude MCP**
4. **在提示时连接到 MCP 服务器**
## 可用功能
桥梁提供以下功能：
- `health_check()`：验证 LM Studio API 是否可访问
- `list_models()`：获取 LM Studio 中所有可用模型的列表
- `get_current_model()`：识别当前加载的模型
- `chat_completion(prompt, system_prompt, temperature, max_tokens)`：使用本地模型生成文本
## 部署选项
该项目支持多种部署方法：
| 方法 | 用例 | 优点 | 缺点 |
|--------|----------|------|------|
| **本地 Python** | 开发，简单设置 | 快速，直接控制 | 需要 Python 设置 |
| **Docker** | 隔离环境 | 清洁，便携 | 需要 Docker |
| **Docker Compose** | 生产部署 | 易于管理 | 更复杂的设置 |
| **Kubernetes** | 企业/规模 | 高度可扩展 | 复杂的配置 |
| **直接 GitHub** | 零设置 | 无需本地安装 | 需要互联网 |
## 已知限制
- 某些模型（例如，phi-3.5-mini-instruct_uncensored）可能存在兼容性问题
- 桥梁当前仅使用 LM Studio 的 OpenAI 兼容 API 端点
- 模型响应将受到本地加载模型的能力的限制
## 故障排除
### API 连接问题
如果 Claude 在尝试连接到 LM Studio 时报告 404 错误：
- 确保 LM Studio 正在运行并且已加载模型
- 检查 LM Studio 的服务器是否运行在端口 1234
- 验证防火墙是否不阻止连接
- 如果问题仍然存在，请尝试在 API URL 中使用“127.0.0.1”代替“localhost”
### 模型兼容性
如果某些模型无法正常工作：
- 某些模型可能不支持 OpenAI 聊天补全 API 格式
- 尝试为有问题的模型使用不同的参数值（温度，最大令牌数）
- 如果问题仍然存在，请考虑切换到更兼容的模型
有关详细的故障排除帮助，请参阅 [TROUBLESHOOTING.md](TROUBLESHOOTING.md)。
## 🐳 Docker 和容器化
该项目包含全面的 Docker 支持：
- **多架构镜像**（AMD64，ARM64/Apple Silicon）
- **自动构建** 通过 GitHub Actions
- **预构建镜像** 在 GitHub 容器注册表中可用
- **Docker Compose** 用于简单部署
- **Kubernetes 清单** 用于生产部署
有关完整的容器化文档，请参阅 [DOCKER.md](DOCKER.md)。
## 贡献
欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 获取指南。
## 许可证
MIT
## 致谢
该项目最初开发为“Claude-LMStudio-Bridge_V2”，现已更名为“LMStudio-MCP”并开源。
---
**🌟 如果这个项目对您有帮助，请考虑给它一个星星！**
