内容
# LMStudio-MCP-本地
MCP 服务器（`lmstudio-mcp-local` 在 npm 上）允许 **LM Studio 读取本地文件路径** 在您的机器上（PDF，DOCX，Markdown，代码，JSON，CSV 等等）。
所有操作都在本地进行 — 文件永远不会上传到云端。
GitHub： [tomaxtoLuca/LMStudio-MCP-LocalPath](https://github.com/tomaxtoLuca/LMStudio-MCP-LocalPath) · 中文文档：[docs/README.zh-CN.md](docs/README.zh-CN.md)
## 概述
**lmstudio-mcp-local** （文件夹：`LMStudio-MCP-Locally`）是一个独立的、只读的 MCP 服务器，通过 [Model Context Protocol](https://modelcontextprotocol.io/) 将 [LM Studio](https://lmstudio.ai/) 连接到您计算机上的文件。
| | |
| -------------- | -------------------------------------------------------------------- |
| **维护者** | [tomaxtoLuca](https://github.com/tomaxtoLuca) |
| **许可证** | [MIT](LICENSE) |
| **运行时** | Node.js ≥ 22 |
| **传输方式** | **stdio** — LM Studio 通过 `command` + `args` 在 `mcp.json` 中启动 |
| **工具** | 7（读取，列表，搜索，查找，批量读取，文件信息，本地推理） |
**有什么不同**
- **LM Studio stdio via `mcp.json`** — 在 `~/.lmstudio/mcp.json` 中注册 `command` + `args` （与 `browser` 相同）；无需手动启动服务器，无需端口 8080。
- **路径允许列表** — 只有您配置的目录是可读的；应用扩展名和大小限制。
- **`reason_over_file`** — 读取本地文件然后调用您的 **本地** LM Studio API；内容保留在您的机器上。
- **文档格式** — PDF，DOCX 和纯文本/代码通过 `pdf-parse` 和 `mammoth`。
**不包括：** 云上传，矢量数据库，文件写入/删除，官方 LM Studio 支持。
## 许可证
[MIT](LICENSE)
## 免责声明和致谢
> **不是法律建议。** 本节阐明项目来源并限制责任。请自行承担风险使用软件。
### 与 LM Studio 无关
该项目 **不是** 由 **LM Studio**，**LM Studio AB** 或任何相关实体开发，支持，赞助或维护。
“LM Studio”仅用于描述 **兼容性** （此 MCP 服务器旨在与 LM Studio 桌面应用程序配合使用）。
不声称商标所有权或官方合作伙伴关系。
### 原创作品
**lmstudio-mcp-local** 是由维护者 **独立开发的原创实现**。它 **不是** LM Studio 的分支，复制品或分发。
第三方 **库** （MCP SDK，`pdf-parse`，`mammoth`等）根据其各自的开源许可证使用；其源代码 **未**嵌入此仓库的`src/`中。
### 作者声明
维护者（[tomaxtoLuca](https://github.com/tomaxtoLuca)）声明，据他所知：
- 该项目 **不是雇佣作品**，并且有权开源。
- 它 **不包含未经授权的第三方代码**。
- **没有雇主或合同限制** 禁止在 MIT 许可证下发布该项目。
如果您认为任何内容侵犯了您的权利，请 [开启一个问题](https://github.com/tomaxtoLuca/LMStudio-MCP-LocalPath/issues)。
### 用户责任
- 谨慎配置 **`allowedPaths`**；仅公开您有权读取的目录。
- 将服务器保留在 **`127.0.0.1`**，除非您了解将其暴露在网络上的风险。
- 您负责 **遵守** 适用的法律，工作场所政策和隐私规则，以读取个人或机密文件。
- 软件按照 MIT 许可证提供 **“AS IS”**；有关完整的保修免责声明和责任限制，请参见 [LICENSE](LICENSE)。
---
## 它做什么
通过 **Model Context Protocol（MCP）** 将您的本地文件系统暴露给 LM Studio。
文件直接从磁盘读取（不是向量搜索，不是云存储）。
```
本地磁盘文件
↓ 直接文件系统读取（在路径允许列表内）
LMStudio-MCP-Locally（MCP 服务器）
↓ MCP 协议
LM Studio 聊天模型
```
---
## 所需组件
| 类型 | 组件 | 需求 |
| ------------- | --------------------------------- | ----------------------------------------------------- |
| **安装** | [Node.js](https://nodejs.org/) | **≥ 22.0.0** |
| **安装** | npm | 捆绑在 Node 中 |
| **安装** | [LM Studio](https://lmstudio.ai/) | 桌面应用程序 |
| **启用** | LM Studio 本地 API | 默认 `http://127.0.0.1:1234` |
| **启用** | 加载模型 | 在 LM Studio 中加载模型 |
| **启用** | 此 MCP 服务器 | LM Studio 通过 `mcp.json` 启动（stdio） |
| **配置** | 路径允许列表 | `allowedPaths` 在 `lmstudio-mcp.json` 或 `MCP_CONFIG`中 |
**不需要：** Python，Docker，矢量数据库，外部数据库。
### 模型要求
| 用例 | 需求 |
| --------------------- | ------------------------------------------- |
| 聊天自动读取文件 | 模型必须支持 **工具使用** |
| `reason_over_file` | 使用 LM Studio 中加载的模型 |
| 长文档 | 受限于模型的 **上下文窗口** |
---
## 系统要求
| 项目 | 需求 |
| ------------- | ------------------------------------------------------------ |
| 操作系统 | Windows 10+ / macOS / Linux |
| Node.js | ≥ 22 |
| 网络 | 需要用于 `npm install`；**不需要读取本地文件** |
| LM Studio API | 默认 **1234**（仅 `reason_over_file`） |
---
## 快速开始
### 选项 A：npm（推荐）
```bash
npm install -g lmstudio-mcp-local
npm run build # 如果从源代码克隆安装
```
LM Studio 将启动服务器 - 您 **不需要** 手动运行 `npm start`。
或者，一次运行，无需安装：
```bash
npx lmstudio-mcp-local
```
复制 `lmstudio-mcp.example.json` 到 `lmstudio-mcp.json` 并设置 `allowedPaths`（推荐在 Windows 上使用 `.env`）。
### 选项 B：从源代码
```bash
git clone https://github.com/tomaxtoLuca/LMStudio-MCP-LocalPath.git LMStudio-MCP-Locally
cd LMStudio-MCP-Locally
npm install
npm run build
```
### 1. 配置允许的本地路径
> **两个不同的配置文件**
>
> | 文件 | 目的 |
> | --------------------------------------------------------------------- | --------------------------------------------------------------- |
> | **`~/.lmstudio/mcp.json`** （例如 `C:\Users\<you>\.lmstudio\mcp.json`） | LM Studio 的 MCP 服务器列表 - 在步骤 3 中添加 `command` + `args` |
> | **`lmstudio-mcp.json`** （安装目录旁边 / 通过 `MCP_CONFIG`） | 此服务器的路径允许列表 - **不** 在 LM Studio 的 UI 中编辑 |
复制 `lmstudio-mcp.example.json` 到 `lmstudio-mcp.json` 在项目根目录（或在 `mcp.json` 中设置 `MCP_CONFIG` 到其完整路径）：
```json
{
"security": {
"allowedPaths": ["F:/Documents", "F:/Projects"]
}
}
```
可选 `.env` （Windows：使用 **分号** 分隔路径，或在 Windows 上更喜欢 JSON）：
```env
# Windows
MCP_ALLOWED_PATHS=F:/Documents;F:/Projects
# macOS / Linux
# MCP_ALLOWED_PATHS=/Users/me/Documents:/Users/me/Projects
```
### 2. 启动 LM Studio
1. 打开 LM Studio
2. **加载** 模型
3. 启用 **本地服务器 / API** （默认端口 1234）- 需要 `reason_over_file`
4. 在聊天设置中启用 **工具使用** （如果支持）
### 3. 在 LM Studio 中添加 MCP 服务器
LM Studio **启动** 此服务器作为子进程通过 stdio - 无需单独的 `npm start`，无需端口 8080。
1. LM Studio → **程序** → **安装** → **编辑 mcp.json**
2. 配置文件：`~/.lmstudio/mcp.json` （Windows：`C:\Users\<you>\.lmstudio\mcp.json`）
3. 在 `mcpServers` 下添加 `command` 条目。 **保留** 任何现有服务器（例如 `browser`）。 **删除** 任何旧的 `"url": "http://127.0.0.1:8080/mcp"` 条目：
```json
{
"mcpServers": {
"browser": {
"command": "node",
"args": ["G:/Lmstudio/LM Studio/.lmstudio/plugins/mcp/browser/index.js"]
},
"lmstudio-mcp-local": {
"command": "node",
"args": ["F:/path/to/lmstudio-mcp-locally/dist/index.js"],
"env": {
"MCP_CONFIG": "F:/path/to/lmstudio-mcp-locally/lmstudio-mcp.json",
"MCP_DEBUG": "false"
}
}
}
}
```
- **`browser`** - stdio MCP；LM Studio 通过 `command` + `args` 启动它
- **`lmstudio-mcp-local`** - stdio MCP；LM Studio 在启动时自动启动它
- **`MCP_CONFIG`** - 您的 `lmstudio-mcp.json` 的完整路径（如果 LM Studio 的 cwd 不是项目文件夹）
- 全局安装后：`"command": "lmstudio-mcp-local"` 和 `"args": []` （确保 npm 全局 bin 在 PATH 上）
4. 保存有效的 JSON（无注释，无尾随逗号），然后重启或重新加载 LM Studio
5. 在聊天中，您应该看到 **7 个本地文件工具** 以及其他 MCP 工具
### 4. 验证本地路径访问
在聊天中：
```
读取 F:/Documents/test.txt 文件
```
如果您看到 `Path not in allowlist`，请将该目录添加到 `lmstudio-mcp.json` 并重启 LM Studio（以重新启动 MCP 进程）。
---
## 可用工具
| 工具 | 描述 |
| --------------------- | ------------------------------------------- |
| `read_file` | 读取单个本地文件 |
| `list_directory` | 浏览目录 |
| `search_in_file` | 文件内关键字搜索 |
| `read_multiple_files` | 一次读取多个文件 |
| `find_files` | 按名称/通配符模式查找文件 |
| `reason_over_file` | 读取文件 + 通过本地 LM Studio API 推理 |
| `get_file_info` | 文件元数据，无需读取内容 |
---
## 配置
### 配置文件位置（`lmstudio-mcp.json`）
按顺序加载（首先找到的为准）：
1. `MCP_CONFIG` 环境变量（在 `~/.lmstudio/mcp.json` → `env` 中设置）
2. `{install-dir}/lmstudio-mcp.json` （在 `package.json` 旁边）
3. `~/.config/lmstudio-mcp/config.json`
4. `./lmstudio-mcp.json` （当前工作目录）
### 高级：HTTP 调试模式 (`--http`)
仅用于 `/health` 检查或 curl 调试 - **不** 是 LM Studio 集成路径：
```bash
npm run start:http
# 或：node dist/index.js --http
```
然后打开 `http://127.0.0.1:8080/health`。通过 `.env` 或 `lmstudio-mcp.json` 中的 `MCP_PORT` 更改端口：
```json
{
"server": {
"port": 9090
}
}
```
### 完整的配置示例（`lmstudio-mcp.json`）
此文件配置 **此 MCP 服务器** （允许列表等）- 不是 LM Studio 的 `~/.lmstudio/mcp.json`。`server.port` 字段仅适用于 `--http` 调试模式。
```json
{
"security": {
"allowedPaths": ["F:/Documents"],
"maxFileSize": 52428800,
"blockedExtensions": [".exe", ".key", ".env"],
"enforcePathGuard": true
},
"reading": {
"maxCharsPerRead": 200000,
"maxListEntries": 500,
"followSymlinks": false
},
"reasoning": {
"lmStudioUrl": "http://127.0.0.1:1234",
"model": "local-model",
"maxContextTokens": 8192,
"temperature": 0.1
}
}
```
---
## 安全
- **路径允许列表** - 只有配置的目录是可读的
- **阻止的扩展名** - `.exe`，`.key`，`.env` 等
- **最大文件大小** - 默认 50MB
- **仅限本地** - stdio 传输；正常使用时无网络监听器
- **`reason_over_file`** - 仅调用本地 LM Studio API
---
## 故障排除
**聊天中未出现工具** - 确认 `dist/index.js` 路径在 `mcp.json` 中正确，`npm run build` 已运行，并且 LM Studio 已重启。删除任何旧的 `"url": "http://127.0.0.1:8080/mcp"` 条目。
**启动/初始化失败** - 检查 Node.js ≥ 22 是否在 PATH 上。手动测试：`node /full/path/to/dist/index.js --help`。确保 `args` 指向 `dist/index.js`，而不是 `src/index.ts`。
**启动后 allowlist 错误** - LM Studio 的 cwd 可能不是项目文件夹。在 `mcp.json` `env` 中设置 `MCP_CONFIG` 到您的 `lmstudio-mcp.json` 的完整路径。
**LM Studio 无法访问** - 确保应用程序已打开，模型已加载，API 已启用（仅限 `reason_over_file`）。
**路径不在允许列表中** - 将目录添加到 `lmstudio-mcp.json`。在 Windows 上，使用正斜杠（例如 `F:/Projects`）；服务器在检查路径时规范化 `\` 与 `/`。
**模型说它无法访问本地文件** - MCP 服务器正常；模型未调用工具。在聊天中启用 **工具使用**。倾向于使用具有可靠函数调用的模型（社区报告使用 tool-capable instruct/coder GGUFs 成功；Gemma 经常拒绝；Qwen3.5 可能发出 LM Studio 无法解析的 XML 工具语法）。
**`Failed to parse tool calls`** （例如 `Expected "<parameter=", but got "<path="`) - 模型输出格式与 LM Studio 的解析器不匹配。切换到另一个模型或显式要求调用 `read_file` 并使用 JSON 参数。
**工具调用待定 / 无反应** - LM Studio 需要首次使用时的批准。点击 **允许** 或 **始终允许来自 mcp/lmstudio-mcp-local 的任何工具**。如果未批准，`read_file` 永远不会运行。
**验证工具执行** - 在 `mcp.json` `env` 或 `.env` 中设置 `MCP_DEBUG=true`，重启 LM Studio。调试日志输出到 **stderr** （stdio 模式必须不写入 stdout）。查找 `[tool] read_file → …ms ✓` 在 LM Studio 的 MCP 日志中。
**`Plugin(mcp/browser): server.getTools is not a function`** - LM Studio 的捆绑浏览器 MCP 插件问题；与此服务器无关。在测试本地文件时从 `~/.lmstudio/mcp.json` 中删除 `browser`，或更新 LM Studio。
**模型未使用工具** - 在聊天设置中启用工具使用；减少测试期间竞争插件（`browser`，`rag-v1`）。
**仅限 HTTP 调试：端口占用** - 另一个 `--http` 实例可能正在运行：
```powershell
# Windows
netstat -ano | findstr :8080
taskkill /PID <pid> /F
```
---
## 开发
```bash
npm run dev # 监视模式（从 src/ 运行）
npm run build # 编译到 dist/
```
---
## 链接
- [GitHub 仓库](https://github.com/tomaxtoLuca/LMStudio-MCP-LocalPath)
- [报告问题](https://github.com/tomaxtoLuca/LMStudio-MCP-LocalPath/issues)
- [模型上下文协议](https://modelcontextprotocol.io/)
- [LM Studio](https://lmstudio.ai/) _(第三方产品；不附属)_
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器