Filesystem MCP：让 LLM 读写本地文件的官方服务器

简介

Filesystem MCP 是 ModelContextProtocol 官方仓库维护的本地文件系统集成服务器。它把文件操作包装为 MCP 工具，让任何兼容 MCP 的客户端都能通过统一协议读写本地文件，核心特色是目录白名单权限控制——只允许访问显式授权的目录，防止 AI 误操作系统文件。

对开发者而言，这意味着：让 AI 助理直接帮你"读一下这个项目的 package.json"、"在 src/utils 下新建一个 helpers.ts"、"搜索所有 .test.ts 文件"。

核心能力

工具名	用途	关键参数
`read_file`	读取单个文件内容	`path`
`read_multiple_files`	批量读取多个文件	`paths[]`
`read_text_file`	读取文本文件（带行号）	`path`
`write_file`	写入文件（覆盖）	`path`、`content`
`create_directory`	创建目录（递归）	`path`
`list_directory`	列出目录内容	`path`
`list_files_with_extensions`	按扩展名过滤	`path`、`extensions[]`
`directory_tree`	递归获取目录树	`path`
`move_file`	移动/重命名文件	`source`、`destination`
`search_files`	按模式搜索文件	`path`、`pattern`（支持通配符）
`get_file_info`	获取文件元信息	`path`（大小、修改时间、权限）
`list_allowed_directories`	列出授权目录	无

注意：不提供 delete_file 工具（安全考虑），删除操作需人工执行。

安全模型：目录白名单

Filesystem MCP 的核心安全机制是启动时指定允许访问的目录：

npx -y @modelcontextprotocol/server-filesystem /path/to/project /path/to/docs

只有 /path/to/project 和 /path/to/docs 下的文件可访问
访问白名单外的路径会被拒绝并报错
符号链接会被解析并检查目标是否在白名单内
.. 路径遍历攻击会被拦截

这是最小权限原则的体现：AI 只能碰你允许它碰的目录。

各客户端配置示例

Claude Code（CLI）

编辑 ~/.claude/claude_desktop_config.json：

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

args 中 @modelcontextprotocol/server-filesystem 之后的所有路径都是授权目录。

Cursor

编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "D:\\Projects",
        "D:\\Documents\\Notes"
      ]
    }
  }
}

Windows 路径用双反斜杠或正斜杠均可。

VS Code（Continue 插件）

编辑 ~/.continue/config.json：

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": [
            "-y",
            "@modelcontextprotocol/server-filesystem",
            "${workspaceFolder}"
          ]
        }
      }
    ]
  }
}

$ {workspaceFolder} 是 VS Code 变量，自动替换为当前工作区路径。

Cline 插件

通过 Cline: MCP Settings 打开配置，结构同 Claude Desktop。

实战场景

场景 1：让 Claude Code 做"项目理解助理"

读取 D:\Projects\myapp 下的 package.json 和 tsconfig.json，
列出所有依赖和 TypeScript 配置，
总结这个项目用了什么技术栈。

Claude Code 会调用 read_multiple_files → 解析 JSON → 格式化总结。

场景 2：让 Cursor 做"批量文件重构"

在 D:\Projects\myapp\src 下搜索所有 .ts 文件，
找出 import 语句中用了 './utils/logger' 的文件，
把这些 import 改为 './utils/logger' 改为 '@/utils/logger'。

Cursor 会调用 search_files → read_multiple_files → 逐个 write_file。

场景 3：让 Claude Code 做"文档生成器"

读取 D:\Projects\myapp\src 下所有 .ts 文件的导出函数，
为每个函数生成 JSDoc 注释，
写回到原文件。

Claude Code 会调用 directory_tree → read_multiple_files → 解析 AST → write_file。

场景 4：让 VS Code 做"项目结构分析"

获取 D:\Projects\myapp 的目录树，
按文件类型统计数量，
找出最大的 5 个文件，
生成一份项目结构报告。

Cline + Continue 会调用 directory_tree → get_file_info → 汇总报告。

与 GitHub MCP 的对比

维度	Filesystem MCP	GitHub MCP
操作对象	本地文件	远程 Git 仓库
版本管理	❌	✅ 原生 Git
协作能力	❌	✅ PR/Issue
读取速度	快（本地 IO）	慢（API 调用）
写入门槛	低	高（需 Token + 分支）
权限控制	目录白名单	Token Scope
适合场景	本地开发、脚本	开源协作、团队项目
是否有删除	❌（安全）	✅

建议两个都装：Filesystem MCP 管本地代码与脚本，GitHub MCP 管远程仓库与协作。本地改完用 GitHub MCP 提交 PR。

注意事项

授权目录要精确：不要授权整个用户目录（C:\Users\yourname），只授权项目目录（C:\Users\yourname\projects\myapp）。
无删除能力：Filesystem MCP 不提供 delete_file，删除需人工执行。这是安全设计，防止 AI 误删。
大文件读取：read_file 对超过 1MB 的文件可能截断，建议先 get_file_info 查大小。
二进制文件：read_file 对图片、PDF 等二进制文件返回乱码，需用专门的 MCP（如 Puppeteer MCP 截图）。
并发写入：多个 AI 客户端同时写入同一文件可能冲突，建议一次只让一个客户端操作。
符号链接：白名单内的符号链接可访问，但目标必须在白名单内。
路径分隔符：Windows 上路径用 \ 或 / 均可，MCP 内部统一处理。
隐藏文件：list_directory 默认包含以 . 开头的隐藏文件（如 .env），注意不要让 AI 读取并泄露密钥。
编码问题：默认按 UTF-8 读取，GBK 编码的中文文件可能乱码，需预处理。

安全建议

最小授权：只授权当前项目目录，不要授权父目录
敏感文件隔离：.env、credentials.json 等放在授权目录外，或用 .gitignore 模式
操作审计：让 AI 在写入前先描述改动，人工确认后执行
只读模式：若只需分析不需修改，可在 Prompt 中明确"只读不写"
定期检查：用 list_allowed_directories 确认授权范围未被意外扩大
备份机制：重要文件用 Git 管理，AI 改坏了可回滚

与内置文件操作的关系

部分 MCP 客户端（如 Claude Code CLI）已内置文件读写能力，无需额外装 Filesystem MCP：

客户端	内置文件能力	是否还需 Filesystem MCP
Claude Code CLI	✅ Read/Write/Edit	可不装，但 SC 提供更丰富的工具（搜索、目录树）
Cursor	✅ 内置文件操作	可不装
VS Code + Continue	❌	建议装
Cline	✅	可不装

结论：Claude Code 和 Cursor 用户可按需装，VS Code 用户建议装。

小结

Filesystem MCP 是开发者最基础的 AI 本地文件入口：目录白名单保证安全、丰富工具覆盖日常文件操作、与 GitHub MCP 互补形成"本地编辑 + 远程协作"闭环。对于需要"读取项目、批量重构、生成文档、分析结构"的开发场景，是必装组件。建议搭配 GitHub MCP（远程协作）和 Notion MCP（文档沉淀）组成开发者三件套。

本系列 MCP Server 介绍至此告一段落。从 Brave Search 的联网搜索，到 Slack/Drive/Notion 的协作集成，到 GitHub/Filesystem 的开发工具——覆盖了 AI 办公与开发的主流场景。下一篇我们将开启新的 MCP 主题系列。