mcp-filesystem

一个加固的文件系统 MCP 服务器。为本地模型提供对你所选目录的读写访问——仅此而已。

基于 MCP TypeScript SDK v2 构建， 针对 2026-07-28 协议修订版，并兼容 2025 时代的客户端，使用相同的端点。 通过 stdio 运行（适用于 LM Studio、Claude Desktop 以及任何派生本地进程的客户端）， 或通过 Streamable HTTP 运行（适用于容器化的共享端点）。

为什么选择这个

大多数文件系统 MCP 服务器只检查路径是否以允许的前缀开头就完事了。 这遗漏了三件重要的事：

• 符号链接。 在沙箱内植入一个指向 /etc 的链接就能完全绕过前缀检查。

• 通过符号链接目录写入。 realpath 对尚不存在的路径会报错，所以只解析已存在文件的服务器 会愉快地在 sandbox/linkdir/payload.sh 中创建文件——而该目录实际指向沙箱之外。

• 前缀冲突。 /data-secrets 以 /data 开头。

本服务器在做出任何决定之前，先将每个路径解析到其物理位置—— 当目标尚不存在时，向上遍历到最深的已存在祖先—— 然后与 realpath 处理后的根目录进行分隔符感知的匹配。测试套件 逐一断言上述每种逃逸都会失败。

Related MCP server: MCP Filesystem Server

工具

写入是原子化的：内容先写入同一目录下的临时文件，执行 fsync， 然后重命名覆盖目标。崩溃或磁盘写满时，原文件保持完整而非被截断。

快速开始

npm install
npm run build
npm test

然后让客户端指向它：

node dist/index.js --root ./workspace

或者不配置客户端，直接交互式试用：

npx @modelcontextprotocol/inspector node dist/index.js --root ./workspace

LM Studio

LM Studio 读取 ~/.lmstudio/mcp.json（在 Windows 上为 C:\Users\<you>\.lmstudio\mcp.json）。打开 程序 → 安装 → 编辑 mcp.json，在 mcpServers 下添加一个条目，然后重新加载 LM Studio。

直接运行

这是最省事的方式，也是推荐的起点。

{
  "mcpServers": {
    "filesystem": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-file-system/dist/index.js",
        "--root", "/absolute/path/to/your/project",
        "--read-only"
      ]
    }
  }
}

一旦信任它，就去掉 --read-only。如需更多目录，添加更多 --root 标志。

这两个路径必须是绝对路径。 宿主进程以不可预测的工作目录派生 子进程，所以相对路径无法解析。在命令行中，你可以控制 工作目录，因此 --root ./workspace 这样的相对路径没问题。

在 Windows 上，要么使用正斜杠（C:/Users/you/projects），要么将 反斜杠加倍，因为单个 \ 在 JSON 字符串中是转义字符。

在 Docker 中运行

Docker 提供了内核级别的边界，位于服务器自身检查之下—— 这才是真正的理由：即使沙箱代码有 bug，也无法触及 你未挂载的任何内容。

docker build -t mcp-filesystem:latest .

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--init",
        "--network", "none",
        "-v", "/absolute/path/to/your/project:/data:ro",
        "mcp-filesystem:latest",
        "--stdio", "--read-only"
      ]
    }
  }
}

注意事项：

• -i 是必需的。没有它，容器无法获得 stdin，JSON-RPC 握手永远不会发生——这是最常见的配置错误。

• --network none 值得设置：此服务器没有理由访问 网络，移除网络接口就消除了一整类数据外泄途径。

• 挂载上的 :ro 让内核来执行只读限制。要允许 写入，去掉 :ro 并且去掉 --read-only。

• Docker 要求 -v 的主机侧路径必须是绝对路径。

• 在 Docker Desktop for Windows 上，你挂载的驱动器必须在 设置 → 资源 → 文件共享中共享。

• 在 Linux 主机上，添加 --user "$(id -u):$(id -g)"，这样写入的文件 归属于你而不是 uid 1000。

通过重复 -v 并传递匹配的 --root 标志来挂载多个目录：

"-v", "/absolute/path/to/your/code:/data/code:ro",
"-v", "/absolute/path/to/your/notes:/data/notes",
"mcp-filesystem:latest",
"--stdio", "--root", "/data/code", "--root", "/data/notes"

HTTP 传输

对于多个客户端共享的长生命周期容器：

docker compose up -d
curl http://127.0.0.1:3000/health

让客户端指向 http://127.0.0.1:3000/。

此服务器没有认证。 任何能访问该端口的人都能获得 服务器所拥有的全部文件系统访问权限。docker-compose.yml 只将端口发布到 127.0.0.1。如果你要绑定到其他地址，请在前面放置一个带认证的反向 代理，并留意启动日志中的警告。

当绑定到回环地址时，服务器会验证 Host 和 Origin 头以 阻止 DNS 重绑定攻击——即你访问的网页将攻击者控制的 域名解析到 127.0.0.1，然后向此端口发送 POST 请求。

配置

每个标志都有对应的环境变量，容器环境使用后者。命令行标志优先。

服务器在没有配置任何根目录时拒绝启动。 没有沙箱的文件系统服务器 不是一个安全的默认值，而默认使用工作目录只会让错误悄无声息地发生。

默认阻止列表

除非传入 --allow-default-denied，否则以下内容被阻止：.env 和 .env.*、*.pem、 *.key、*.p12、*.pfx、*.keystore、id_rsa/id_dsa/id_ecdsa/ id_ed25519、.ssh/、.aws/、.gnupg/、.kube/config、.npmrc、.netrc、 .pypirc、.docker/config.json、.git/、.svn/、.hg/、shadow。

这样做的目的是让粗心的 -v $HOME:/data 不至于酿成灾难。这是一个安全 网，而不是正确挂载目录的替代品。

安全模型

强制执行的内容

• 每次包含性判定之前都进行物理路径解析（realpath）， 包括尚不存在的路径

• 分隔符感知的根目录匹配（/data 永远不会匹配 /data-secrets）

• 默认拒绝符号链接，且在任何路径位置——不仅仅是叶节点

• NUL 字节拒绝（safe.txt\0/../../etc/passwd 会在系统调用中被截断）

• Windows：备用数据流（file:stream）、保留设备名 （CON、NUL、COM1…）、设备命名空间路径（\\?\、\\.\），以及 不区分大小写的包含性判定

• 只读模式在处理器运行之前就拦截修改类工具

• move/copy 的两个操作数都进行检查——只检查源路径 等于给整个主机开了一个写入后门

• 允许的根目录本身不能被删除或移动

• 在分配内存之前通过 stat 检查大小上限

• 二进制检测，避免将二进制文件作为消耗 token 的垃圾返回

• 对 grep_files 进行正则筛查并设置墙钟截止时间

• 错误消息从不回显主机路径；SecurityError 向模型返回模糊消息， 将真实原因记录到审计流中，这样沙箱就不会成为映射你文件系统的预言机

不强制执行的内容

• TOCTOU（检查时间到使用时间竞态）。 在解析路径和打开它之间， 一个能在你的允许根目录内写入的本地攻击者可能将文件替换为符号链接。 要解决这个问题，需要在 Linux 上使用 openat2(RESOLVE_BENEATH)， 而 Node 并未暴露此接口。实际的缓解措施是容器边界—— 只挂载你确实想暴露的内容。

• 认证。 两种传输方式都不认证。stdio 继承派生进程者的信任； HTTP 仅限回环地址正是出于这个原因。

• 资源耗尽。 上限和截止时间约束了大多数情况，但一个 病态的正则表达式仍可能烧掉一个 15 秒截止时间的 CPU。compose 文件 设置了内存和 CPU 限制。

• 提示注入。 如果你的沙箱内某个文件包含指令，而你的 模型遵循了这些指令，这个服务器会忠实地执行模型接下来 调用的任何工具。只读模式是真正有效的缓解措施。

容器加固（在 docker-compose.yml 中）：非 root 用户、read_only 根文件系统、删除所有能力、no-new-privileges、tmpfs /tmp、 内存和 CPU 限制。

审计日志

每行一个 JSON 对象，输出到 stderr——绝不输出到 stdout，因为 stdout 是 stdio 模式下的 JSON-RPC 通道。启动时 console.log 被猴子补丁重定向到 stderr， 这样一条意外的调试语句就不会破坏协议流。

{"ts":"2026-08-21T19:12:03.441Z","tool":"read_file","outcome":"ok","durationMs":3,"paths":["src/index.ts"],"bytes":4821}
{"ts":"2026-08-21T19:12:07.882Z","tool":"read_file","outcome":"denied","durationMs":1,"detail":"physical containment failed: /data/../etc/passwd -> /etc/passwd"}

记录的路径是沙箱相对路径。detail 字段携带完整原因， 且只写入此处，绝不返回给模型。

docker compose logs -f filesystem | jq 'select(.outcome=="denied")'

测试

npm run build && npm test

test/sandbox.test.ts 才是真正重要的测试套件——每个用例都是 试图访问根目录之外文件的尝试。如果其中任何一个本该抛出异常 的用例开始通过，说明服务器在唯一真正危险的方式上出了问题。

符号链接测试在 Windows 上会自行跳过，除非开启了开发者模式， 因为在其他情况下创建符号链接需要管理员权限。

项目结构

src/
  index.ts              entrypoint, transport selection, shutdown
  config.ts             CLI + env parsing, root resolution
  security/
    sandbox.ts          path resolution and containment — the security core
    audit.ts            structured stderr logging, stdout protection
  tools/
    context.ts          registration wrapper: read-only gate, errors, audit
    read.ts             read_file, read_multiple_files, get_file_info, ...
    write.ts            write_file, append_file, edit_file
    listing.ts          list_directory, directory_tree
    manage.ts           create_directory, move_file, copy_file, delete_file
    search.ts           search_files, grep_files
  util/
    walk.ts             sandbox-aware directory traversal with cycle guard
    binary.ts           binary detection, BOM handling
    errors.ts           error taxonomy and fs error translation
    format.ts           output formatting for model consumption

许可证

MIT