MCP Filesystem Server：为 AI 打开安全文件系统访问的标准实现
深度解析 MCP 官方参考实现 @modelcontextprotocol/server-filesystem：13 个文件系统工具、基于 Roots 协议的动态目录访问控制、完整的 ToolAnnotations 安全标注体系，以及 NPX/Docker/VS Code 多平台部署方案。
项目概述
Filesystem MCP Server 是 MCP 官方参考实现之一，位于 modelcontextprotocol/servers 仓库中，npm 包名为 @modelcontextprotocol/server-filesystem，MIT 协议开源。它为 LLM 提供安全的文件系统访问能力，是 MCP 生态中最基础也最重要的服务端之一。
工具体系
项目提供 13 个工具，分为四类：
- 读取类：
read_text_file（支持 head/tail 行数限制，始终按 UTF-8 处理）、read_media_file（base64 编码返回图片/音频，其他文件作为 embedded resource）、read_multiple_files（批量读取，单文件失败不影响整体操作）。 - 写入类：
write_file（创建或覆盖文件）、edit_file（基于行匹配的精确编辑，支持dryRun预览和 Git 风格 diff 输出，自动检测和保留缩进风格）。 - 目录类：
create_directory、list_directory、list_directory_with_sizes（含排序和汇总统计）、directory_tree（JSON 递归树结构）、move_file、search_files（Glob 模式匹配，支持排除规则）。 - 元数据类：
get_file_info（大小、创建/修改/访问时间、类型、权限）、list_allowed_directories（当前可访问目录列表）。
安全模型
目录访问控制支持两种模式。命令行参数模式在启动时通过位置参数指定允许目录。Roots 协议模式（推荐）利用 MCP 客户端的 roots 能力动态下发允许目录，支持运行时通过 roots/list_changed 通知更新权限而无需重启服务端。若启动时既无命令行参数、客户端也不支持 roots 协议，服务端会在初始化时报错。
此外，每个工具都设置了 ToolAnnotations：readOnlyHint 区分 9 个只读工具和 4 个可写工具，idempotentHint 标注 create_directory（重复创建为 no-op）和 write_file 为幂等，destructiveHint 标注 write_file、edit_file、move_file 为破坏性操作。所有工具均设 openWorldHint: false。
使用方式
NPX 一行命令即可运行：
npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/dirDocker 模式通过 bind mount 将宿主机目录挂载到容器的 /projects 路径，支持 ro 只读标记。VS Code 提供一键安装按钮，支持用户级（mcp.json）和项目级（.vscode/mcp.json）配置。Windows 下需通过 cmd /c 包装 npx 调用。
总结
Filesystem MCP Server 是 MCP 工具设计的一个范本：工具职责划分清晰（读/写/目录/元数据四类）、安全模型层层递进（CLI 参数 → Roots 协议 → 目录限制 → ToolAnnotations 标注）、部署方式灵活（NPX、Docker、VS Code 一键安装）。对于需要让 AI 读写本地文件的场景，它是 MCP 生态中的首选方案，也是学习 MCP 服务端开发的最佳参考实现之一。
项目地址：github.com/modelcontextprotocol/servers
npm 包：@modelcontextprotocol/server-filesystem
开源协议：MIT