Filesystem MCP：让 AI 安全读写你的本地文件

为什么需要 Filesystem MCP

你大概经历过这种场景：

你：帮我把这个项目所有组件的 console.log 删掉
AI：好的，请把每个文件的内容粘贴给我，我逐个改完再贴回去...
你：（50 个文件，3 小时过去了）

没有文件访问能力的 AI，只能做"问答机器"，做不了"执行助手"。

Filesystem MCP 解决的就是这个问题——让 AI 能直接读写你授权目录下的文件，但又不失控。

核心能力

能力	工具名	说明
读文件	`read_file`	读取单个文件内容，支持文本与二进制（图片转 base64）
读多文件	`read_multiple_files`	批量读取，减少往返
列目录	`list_directory`	列出指定目录下所有文件与子目录
目录树	`directory_tree`	递归生成目录树（JSON 结构）
搜索文件	`search_files`	按名称模式递归搜索
写文件	`write_file`	创建或覆盖文件
编辑文件	`edit_file`	局部替换（精准字符串匹配）
创建目录	`create_directory`	递归创建目录
移动	`move_file`	移动或重命名
搜索内容	`search_files`	在文件内容中检索
获取信息	`get_file_info`	文件元信息（大小、修改时间、权限）
列允许目录	`list_allowed_directories`	查询当前会话可访问的目录

安装与配置

前置要求

Node.js 18+
已安装支持 MCP 的客户端

各客户端配置

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

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

关键：args 最后的路径是允许访问的目录白名单，AI 只能访问这些目录，白名单外一律拒绝。

Cursor

在 Settings → MCP 中添加，或编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/allowed/dir"
      ]
    }
  }
}

VS Code（Continue 插件）

编辑 ~/.continue/config.json：

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "name": "filesystem",
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": [
            "-y",
            "@modelcontextprotocol/server-filesystem",
            "/path/to/project"
          ]
        }
      }
    ]
  }
}

验证安装

重启客户端后，输入：

列出我能访问的所有目录

AI 会调用 list_allowed_directories 返回白名单，确认配置成功。

三重安全机制

1. 目录白名单

启动时通过命令行参数指定：

npx -y @modelcontextprotocol/server-filesystem /safe/dir1 /safe/dir2

AI 访问 /etc/passwd 或 ~/.ssh 会直接被拒绝：

错误：路径 /etc/passwd 不在允许的目录内

2. 路径规范化校验

所有路径会先做规范化处理，防止以下绕过手段：

攻击：/safe/dir/../../../etc/passwd
防御：规范化为 /etc/passwd → 拒绝

攻击：/safe/dir/./../../etc/passwd
防御：规范化为 /etc/passwd → 拒绝

攻击：符号链接 /safe/dir/link → /etc/passwd
防御：解析符号链接后校验真实路径

3. 操作粒度可控

操作	默认	可配置
读	允许	-
写	允许	可禁用（只读模式）
删除	允许	可禁用
移动	允许	可禁用

只读模式启动：

{
  "args": [
    "-y",
    "@modelcontextprotocol/server-filesystem",
    "--read-only",
    "/path/to/dir"
  ]
}

实战场景

场景 1：批量代码重构

你：把 src/components 下所有 .jsx 文件改为 .tsx，并加上 TypeScript 类型声明
AI：
  1. list_directory src/components
  2. for each .jsx:
       read_file → 分析 props
       write_file .tsx → 带 TS 类型的版本
       move_file .jsx → .bak
  3. 报告：12 个文件转换完成，3 个有复杂 props 需人工确认

场景 2：文档批量生成

你：读 README.md，提取每个 API 的签名，在 docs/api/ 下生成对应的 .md 文件
AI：
  1. read_file README.md
  2. 解析出 15 个 API
  3. create_directory docs/api
  4. for each API: write_file docs/api/{name}.md

场景 3：日志分析

你：扫描 logs/ 目录下所有 .log 文件，找出最近 24 小时的 ERROR，汇总成 report.md
AI：
  1. list_directory logs/
  2. search_files logs/ "*.log"
  3. for each: read_file + grep ERROR
  4. write_file report.md

场景 4：项目结构梳理

你：给当前项目画一棵目录树，标注每个目录的用途
AI：
  1. directory_tree .
  2. read_file 关键配置文件（package.json / README）
  3. 输出带注释的目录树

输出示例：

my-project/
├── src/                  # 源代码
│   ├── components/       # React 组件
│   ├── lib/              # 工具函数
│   └── app/              # Next.js App Router
├── content/              # MDX 内容
├── public/               # 静态资源
├── scripts/              # 构建/部署脚本
└── package.json          # 依赖配置

局部编辑示例

edit_file 工具支持精准的字符串匹配替换，避免整文件覆盖：

工具调用：
{
  "tool": "edit_file",
  "arguments": {
    "path": "/project/src/config.ts",
    "edits": [
      {
        "oldText": "const API_URL = 'https://dev.example.com';",
        "newText": "const API_URL = 'https://prod.example.com';"
      },
      {
        "oldText": "export const DEBUG = true;",
        "newText": "export const DEBUG = false;"
      }
    ]
  }
}

如果 oldText 在文件中出现多次，工具会要求你提供更多上下文以精准定位，避免误改。

与其他 MCP 的协作

Filesystem MCP 很少单独使用，常与其他 MCP 组合：

组合	场景
Filesystem + GitLab MCP	本地改完代码直接提交 MR
Filesystem + GitHub MCP	读取 issue → 改代码 → 提 PR
Filesystem + Brave Search	联网调研 → 写入本地文档
Filesystem + Memory MCP	记住项目结构偏好，下次自动应用

注意事项

1. 大文件性能

读取 100MB+ 的日志文件会超时。建议先用 search_files 定位行号，再用 read_file 的 offset/limit 分段读取。

2. 二进制文件

图片、PDF 等二进制文件会被转为 base64 返回，体积膨胀 33%。大批量处理图片建议用专用 MCP。

3. 并发写冲突

多个 AI 会话同时写同一文件会冲突。建议：

关键文件加锁（在 Prompt 中告知 AI）
写入前先 get_file_info 检查修改时间

4. 符号链接

默认会解析符号链接的真实路径。如果你的项目用 symlink 关联 monorepo 子包，确认白名单包含所有真实路径。

5. 权限问题

服务进程的用户身份决定文件访问权限。在 macOS/Linux 上若服务以 nobody 启动，可能读不到 home 目录下的文件。

与直接执行 shell 的区别

维度	Filesystem MCP	Bash/Shell 工具
安全模型	白名单 + 路径校验	完全信任
可控性	高（粒度到操作）	低（任意命令）
适用场景	文件读写	系统管理
风险	低	高（rm -rf 事故）

建议：日常文件操作用 Filesystem MCP；构建/部署等需要 shell 的场景用专用 MCP 并加命令白名单。

小结

Filesystem MCP 是 AI 工程化最基础的一块拼图——让 AI 从"会说"变成"会做"。配合目录白名单与只读模式，既释放了 AI 的生产力，又把风险控制在可接受范围内。

下一步建议：在你的主力项目上配置 Filesystem MCP，让 AI 帮你做一次代码梳理或文档生成，你会立刻感受到"AI 真的能干活了"。