内容
# llmstudio-mcp
[简体中文](README.zh.md)
MCP 服务器，用于将本地 [LM Studio](https://lmstudio.ai) 实例暴露给 LLM 代理 — 列出/加载/卸载模型，运行聊天和文本补全，生成嵌入，并通过原始逃生门户访问任何其他 LM Studio REST 端点。
## 目录
- [工具](#工具)
- [环境变量](#环境变量)
- [前提条件](#前提条件)
- [连接](#连接)
- [本地运行](#本地运行)
## 工具
| 工具 | 参数 | 描述 |
|------|-----------|-------------|
| `list_models` | `type: "all" \| "llm" \| "embedding" \| "vlm" = "all"` | 列出已下载的模型及其元数据（类型、状态、上下文长度、量化） |
| `get_model` | `model_key: str` | 获取单个模型的详细信息 |
| `get_loaded_models` | — | 当前加载到内存中的模型 |
| `load_model` | `model_key, context_length?, flash_attention?, offload_kv_cache_to_gpu?, num_experts?, eval_batch_size?` | 将模型加载到内存中 |
| `unload_model` | `instance_id: str` | 从内存中卸载模型 |
| `chat` | `model, messages, temperature?, max_tokens?, top_p?, top_k?, stop?, stream?, tools?` | OpenAI 兼容的聊天补全 (`/v1/chat/completions`) |
| `complete` | `model, prompt, temperature?, max_tokens?, top_p?, top_k?, stop?, stream?` | OpenAI 兼容的文本补全 (`/v1/completions`) |
| `embed` | `model, input, normalize=false` | OpenAI 兼容的嵌入 (`/v1/embeddings`) |
| `raw_request` | `method, path, json_body?` | 访问任意 LM Studio REST 端点的逃生门户 |
## 环境变量
| 变量 | 是否必需 | 默认值 | 描述 |
|---------|----------|---------|-------------|
| `LMSTUDIO_MCP_BASE_URL` | 否 | `http://localhost:1234` | LM Studio 服务器 URL |
| `LMSTUDIO_MCP_API_KEY` | 否 | 空字符串 | API token（仅在 LM Studio 的开发者选项卡中启用了 token 认证时需要） |
| `LMSTUDIO_MCP_TIMEOUT` | 否 | `60.0` | HTTP 超时时间（秒）；针对慢模型或大型生成任务时可调大 |
## 前提条件
LM Studio 运行并启用其 API 服务器 — 桌面应用的开发者选项卡启用，或通过 CLI 运行 `lms server start`。至少有一个模型已下载 (`lms get <model>`).
## 连接
唯一要求：`uv` (https://docs.astral.sh/uv/). 无需安装其他依赖。
### Claude 代码
```bash
claude mcp add llmstudio-mcp -- uvx --from git+https://github.com/dam2452/llmstudio-mcp.git llmstudio-mcp
```
如果在 LM Studio 中启用了 API token 认证：
```bash
claude mcp add llmstudio-mcp -e LMSTUDIO_MCP_API_KEY=<token> -- uvx --from git+https://github.com/dam2452/llmstudio-mcp.git llmstudio-mcp
```
### Claude 桌面版 / 其他 MCP 客户端
```json
{
"mcpServers": {
"llmstudio-mcp": {
"command": "uvx",
"args": ["--from", "git+https://github.com/dam2452/llmstudio-mcp.git", "llmstudio-mcp"]
}
}
}
```
推送新版本后：`uv cache clean` 并重启客户端。
## 本地运行
```bash
uv run --directory . llmstudio-mcp
```
测试（手动）：
```bash
uv run --directory . --with pytest pytest test/
```
