Filesystem MCP Server 实战：让智能体安全读写本地文件的配置方法

云上的幻象2026-10-046 分钟阅读2,296 字20

100%

Filesystem MCP Server 实战：让智能体安全读写本地文件的配置方法

Filesystem MCP Server 是什么：给模型一个带围栏的文件通道

Filesystem MCP Server 是 MCP 官方参考实现之一，用一句话定位：让大模型在你的电脑上读写文件，但只能碰你明确授权的目录。所有操作被限制在启动参数指定的允许目录里，路径校验防目录穿越，越界一律拒绝——这是它和「直接把 shell 权限给模型」的本质区别。

它解决的场景很常见：让 Claude 或其他 MCP 客户端整理下载目录、读日志找报错、批量改代码文件、生成报告写到指定文件夹。没有它，模型只能输出代码让你自己执行；有了它，整条流程能自动跑完。

安装与配置：npx 一行起步

官方包是 @modelcontextprotocol/server-filesystem，启动参数就是允许目录列表：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:/Users/yourname/Documents",
        "C:/Users/yourname/Projects"
      ]
    }
  }
}

把这段加进 Claude Desktop 的 claude_desktop_config.json（或 Cursor 、 VS Code 等客户端的 MCP 配置），重启客户端即可。 Docker 方式则需要把宿主机目录挂载到容器的 /projects 下再加 ro 标记只读。

确认本机有 Node.js，在客户端 MCP 配置里加上面的 JSON，路径换成你自己的目录。

重启客户端，让它列出可用工具，确认出现 read_text_file 、 write_file 、 directory_tree 等。

问一句「列出我的 Projects 目录」，验证 list_directory 正常返回。

故意让它访问允许目录之外的路径（如系统盘根目录），确认被拒绝——这是安全围栏在工作。

日常只把工作目录加进参数，敏感目录（含凭证、私人文件）永远不进白名单。

核心工具清单

工具	用途
read_text_file / read_multiple_files	读单个或多个文件，支持 head/tail 行数截取
write_file / edit_file	写文件；edit_file 支持 oldText/newText 定点替换，带 `dryRun` 预览 diff
create_directory / list_directory / directory_tree	建目录、列目录、递归输出 JSON 树
move_file / search_files	移动改名；按名称模式（支持排除规则）递归搜索
get_file_info / list_allowed_directories	查元数据；查看当前允许目录（安全审计用）

edit_file 官方建议永远先用 dryRun: true 预览变更，确认 diff 无误再正式执行，能省掉大量误改返工。

安全红线：三条必须守住

白名单最小化：只授权任务需要的目录。允许目录就是沙箱边界，把它开到用户根目录等于没有围栏；
敏感目录永不进白名单：存放密钥、凭证、浏览器配置的目录不授权；要读配置就复制一份到工作区；
删除与移动类操作加确认：批量整理文件前，先让模型列计划（dryRun 思路）人工过目，再放行执行。

进阶：Roots 协议动态调整授权

新版本的 Filesystem Server 支持 MCP Roots 协议：客户端可以在运行时通过 roots/list_changed 通知动态更新允许目录，无需重启服务器。客户端传了 Roots 时会整体替换命令行参数指定的目录；不支持 Roots 的客户端则回退到启动参数。个人客户端场景用命令行参数最省事，构建需要动态切换工作区的产品时再看 Roots 。

Filesystem Server 通常是你接入的第一个 MCP 服务，但绝不该是最后一个：