Docker 部署 Filesystem MCP Server 如何配置目录挂载（/projects 约定与 ro 只读参数）

在 MCP 客户端（Claude Desktop、VS Code 等）里通过 Docker 运行 Filesystem MCP Server 时，核心问题不是"怎么跑起来"，而是怎么把本机哪些目录交给服务器、哪些目录只允许它读。Filesystem Server 是 servers 仓库中基于 Node.js 的文件系统 MCP 参考实现，npm 包名为 @modelcontextprotocol/server-filesystem。官方约定：所有要交给服务器的目录都必须挂载到容器内的 /projects 前缀下，并在配置末尾把 /projects 作为参数传给服务器；某条挂载末尾追加 ro 后，该目录对服务器变为只读。本文给出从构建镜像、写挂载配置到验证结果的一条完整路径，依据来自 src/filesystem/README.md 与 src/filesystem/Dockerfile。

一、先构建 mcp/filesystem 镜像

文档示例统一使用镜像名 mcp/filesystem。如果本地还没有这个镜像，在仓库根目录执行（README "Build" 一节给出的原命令）：

docker build -t mcp/filesystem -f src/filesystem/Dockerfile .

这条命令用仓库根目录作为构建上下文、src/filesystem/Dockerfile 作为构建文件。该 Dockerfile 是两段式构建：builder 阶段基于 node:22.12-alpine 安装依赖并编译，release 阶段基于 node:22-alpine，入口为 node /app/dist/index.js。如果你已有同名的 mcp/filesystem 镜像，可跳过本步。

二、/projects：所有挂载的统一前缀

src/filesystem/README.md 的 Docker 小节有两条硬性约定：

• "all directories must be mounted to /projects by default" —— 每一条 --mount 的 dst 都必须是 /projects 下的路径；
• 配置 args 的最后一项是 /projects，作为命令行参数传给服务器，即服务器允许的目录（对应 README "Method 1: Command-line Arguments" 中 mcp-server-filesystem /path/to/dir1 ... 的用法）。

以 Claude Desktop 为例，把下面配置加入 claude_desktop_config.json：

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount", "type=bind,src=/Users/username/Desktop,dst=/projects/Desktop",
        "--mount", "type=bind,src=/path/to/other/allowed/dir,dst=/projects/other/allowed/dir,ro",
        "--mount", "type=bind,src=/path/to/file.txt,dst=/projects/path/to/file.txt",
        "mcp/filesystem",
        "/projects"
      ]
    }
  }
}

这是文档原样给出的配置，其中需要你替换的值只有 src：

• src 是本机真实绝对路径。文档示例用 /Users/username/Desktop 这类写法占位，替换成你要开放给服务器的目录即可；
• dst 必须在 /projects 之下，容器内路径结构由你自己定（示例中 Desktop、other/allowed/dir 都是自定义的容器内路径）；
• 第三条挂载说明单个文件也可以挂载（示例挂载了 file.txt 这一个文件），此时 dst 同样落在 /projects 下；
• -i 与 --rm 是文档示例中 docker run 的原有参数，按原样保留。

三、ro 参数：让某个挂载目录对服务器只读

README 的原话："you can provide sandboxed directories to the server by mounting them to /projects. Adding the ro flag will make the directory readonly by the server."

也就是说，只读不是单独的配置项，而是逐条挂载控制的：哪条 --mount 行末尾追加 ,ro，哪个目录就对服务器只读。比如示例中的：

--mount "type=bind,src=/path/to/other/allowed/dir,dst=/projects/other/allowed/dir,ro"

这个目录允许服务器读，不允许写；不需要只读保护的其他挂载行则不加 ro，服务器可以正常执行 write_file、create_directory 等写操作（README 的工具列表和 ToolAnnotations 表把 write_file、edit_file、move_file 标记为可写、可能破坏性的工具）。文档没有提供比"整目录只读 / 可写"更细的权限档位，按挂载粒度控制就是文档给出的全部方式。

四、验证：确认服务器实际允许的目录

配置保存后，客户端通过 docker 启动容器并建立连接。文档给出的核对手段是 list_allowed_directories 工具（无需输入参数），它返回服务器当前被允许访问的目录列表，应与配置中各条 dst 在 /projects 下的路径对应。README 同时明确：

All filesystem operations are restricted to allowed directories

即所有文件系统操作都被限制在允许目录内，允许目录之外读写不到。

文档还给出了一个明确的失败现象用于判断配置是否漏项：如果服务器启动时没有任何命令行目录参数，且客户端不支持 Roots 协议（或提供空的 roots），服务器会在初始化阶段抛错；同时"Server requires at least ONE allowed directory to operate"。因此如果连接直接初始化失败，先检查配置末尾的 /projects 参数和各条 --mount 是否还在。

五、注意：支持 Roots 的客户端会覆盖服务端目录

如果你的客户端支持 Roots 协议，服务器在初始化时会通过 roots/list 向客户端要 roots，客户端返回的 roots 会完全替换服务器侧由 /projects 参数配置的允许目录；运行中客户端发 notifications/roots/list_changed 后还会再次替换。所以用 list_allowed_directories 看到的目录与配置文件里的 dst 不一致时，先检查客户端的 Roots 配置，而不是先怀疑挂载写错。客户端不支持 Roots 时，服务器则始终使用命令行（即 /projects 参数）指定的目录，且无法动态更新。

六、可选分支：在 VS Code 中用 ${workspaceFolder} 挂载

同样的 Docker 方式可以配进 VS Code 的 MCP 配置（命令面板执行 MCP: Open User Configuration 打开用户级 mcp.json，或写入工作区 .vscode/mcp.json），src/filesystem/README.md 给出的示例是：

{
  "servers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount", "type=bind,src=${workspaceFolder},dst=/projects/workspace",
        "mcp/filesystem",
        "/projects"
      ]
    }
  }
}

这里 ${workspaceFolder} 是 VS Code 解析的变量，指当前工作区目录，不需要手动替换。该示例没加 ro，工作区因此是服务器可写的；想让工作区只读，按第三节在挂载行末尾追加 ,ro。

限制说明

• 只读控制粒度是单条挂载目录，ro 是文档给出的唯一只读手段，没有更细的权限配置；
• 仓库根 README.md 声明这些服务器是参考实现，用于演示 MCP 特性与 SDK 用法，"not as production-ready solutions"，生产使用需自行评估安全要求。