mcplocal

本地文件 MCP 服务器，允许支持 MCP 的客户端（包括可用的 ChatGPT Web 自定义 MCP 应用）在一个明确配置的目录内读取、搜索和修改文件。

功能特性

• 旧版 HTTP+SSE：GET /sse + POST /messages

• 新版 MCP HTTP 端点：/mcp

• 健康检查：/health

• 沙箱：所有文件路径均在 MCP_ROOT 下解析

• 可选 Bearer 认证

• 用于项目探索的读取/搜索工具

• 用于编码工作流的写入/编辑工具

• 默认禁用删除

• 无 shell/CLI 执行工具

• 不依赖外部数据库

• Node.js 20+

MCP TypeScript SDK 目前建议远程服务器使用 Streamable HTTP，并将 HTTP+SSE 视为向后兼容的传输方式。本项目有意同时提供这两种方式，以便旧版 SSE 客户端仍可连接，而新版客户端可使用 /mcp。

Related MCP server: FilesystemMCP

1. 运行

cp .env.example .env
# edit MCP_ROOT if needed
npm start

示例：

MCP_ROOT=~/Projects
MCP_HOST=127.0.0.1
MCP_PORT=8008
MCP_AUTH_TOKEN=change-me

然后：

SSE:        http://127.0.0.1:8008/sse
Streamable: http://127.0.0.1:8008/mcp
Health:     http://127.0.0.1:8008/health

2. ChatGPT Web 可以连接什么

ChatGPT Web 无法从托管服务直接访问 localhost。本地 MCP 服务器必须通过受支持的 Secure MCP Tunnel/私有网络机制才能被访问到。获得远程 MCP 端点后，在 ChatGPT Developer Mode 中将其添加为自定义 MCP 应用，扫描其工具并启用它。

对于映射本地服务的隧道，本地源为：

http://127.0.0.1:8008/sse

或者，对于新版客户端：

http://127.0.0.1:8008/mcp

不要在未启用认证和明确网络策略的情况下将此服务器暴露到公共互联网。

3. 向 ChatGPT 公开的工具

• list_files(path, recursive)

• read_file(path, startLine, endLine)

• write_file(path, content, createDirs)

• edit_file(path, oldText, newText, replaceAll)

• search_files(query, path, regex, caseSensitive, maxResults)

• create_directory(path)

• file_info(path)

• delete_file(path) 仅在 MCP_ENABLE_DELETE=true 时

典型编码工作流：

1. 使用 list_files 了解项目。

2. 使用 search_files 定位符号。

3. 使用 read_file 检查相关代码。

4. 使用 edit_file 进行精准修改，或使用 write_file 创建新文件。

5. 再次使用 read_file 验证结果。

4. 安全模型

MCP_ROOT 是硬性边界。../ 路径穿越以及其外的绝对路径都会被拒绝。搜索会跳过二进制/不可读文件。文件大小受 MCP_MAX_FILE_BYTES 限制。

服务器有意不暴露任意 shell 执行能力。这意味着 ChatGPT 可以编辑代码，但不能通过此 MCP 自动运行 rm、curl、包管理器、git 命令或任意程序。

对于开发机器，请将 MCP_HOST 保持为 127.0.0.1，并使用受支持的 Secure MCP Tunnel，而不要将服务器绑定到所有网络接口。

5. 构建

npm run build
node dist/server.js

构建过程无依赖，并将运行时复制到 dist/。

6. Docker

docker build -t mcplocal .
docker run --rm -p 8008:8008 -v "$PWD:/workspace" mcplocal

7. ChatGPT 中的示例提示

Inspect this local project and tell me where the authentication flow is implemented. Do not modify anything.

Open src/server.js and refactor the error handling. Before changing it, read the relevant code. Then edit only the necessary section and show me what changed.

Search the project for TODO comments and create a report at reports/todos.md.

许可证

MIT