@modelcontextprotocol/server-filesystem

@modelcontextprotocol/server-filesystem 是 Model Context Protocol（MCP）官方维护的文件系统访问服务器，由 MCP 官方团队（Anthropic 等）开发和维护。它为 AI 编程助手提供安全、可靠的文件系统读写能力，是目前最受欢迎、使用最广泛的 MCP 服务器之一，每周下载量超过 280 万次。

核心能力

该服务器将本地文件系统以 MCP 资源（Resource）和工具（Tool）的形式暴露给 AI 助手，核心能力包括：

文件系统读取： 读取任意文本/代码文件内容，支持指定编码；递归列出目录结构；获取文件元数据（大小、修改时间、权限等）。

文件系统写入： 创建新文件；覆盖或追加写入现有文件；自动创建父目录。

目录操作： 列出目录内容（支持递归深度控制）；搜索匹配特定模式的文件。

批量操作： 支持同时处理多个文件路径；提供路径验证和安全检查。

安装配置

前提条件：

• Node.js ≥ 20（LTS 版本推荐）
• npm、pnpm 或 yarn

通过 npx 直接运行（推荐）：

npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/directory

其中 /path/to/allowed/directory 是允许 AI 访问的根目录（安全沙箱）。

MCP 客户端配置示例：

{ "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/your/workspace/path"], "env": {} } } }

配置文件方式（Claude Desktop 等）：

在 claude_desktop_config.json 中添加：

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

使用步骤

第一步：确定工作目录 决定 AI 助手可以访问哪个根目录。出于安全考虑，不建议设置为系统根目录 /，推荐使用项目文件夹或工作区路径。

第二步：配置 MCP 客户端 将上述配置添加到你的 AI 编程助手配置文件中。支持的客户端包括：Claude Desktop、Cursor、Cline、VS Code Copilot（WIP）等。

第三步：验证连接 启动 AI 助手，发送指令测试文件系统访问，例如：

• "列出当前目录的所有文件"
• "读取 README.md 的内容"
• "在 src 目录下创建一个新文件"

第四步：开始使用 确认文件操作正常工作后，即可在日常开发中通过自然语言指令让 AI 读写、创建、搜索项目文件。

适用场景

代码阅读与理解： AI 助手可以直接读取整个代码库的文件，帮助理解项目结构、分析代码逻辑、定位 Bug。

自动化代码生成与写入： 让 AI 生成代码后直接写入文件，减少手动复制粘贴的步骤。

文档处理： 批量读取、处理、生成项目文档，如 API 文档、变更日志、技术规范。

代码重构辅助： AI 可以读取多个相关文件，理解上下文后协助进行跨文件的代码重构。

数据文件操作： 读写 JSON、CSV、XML 等配置文件，以及日志文件的分析处理。

适用人群

• 使用 Claude、Cline、Cursor 等 AI 编程助手的开发者
• 需要 AI 辅助进行代码阅读、重构、生成的团队
• 希望 AI 能直接读写项目文件而非依赖剪贴板的用户
• 构建自动化开发工作流的 DevOps 和平台工程师

工作原理

@modelcontextprotocol/server-filesystem 基于官方 MCP SDK 构建，实现了 MCP 协议规范中的 Resources（资源）和 Tools（工具）接口。

安全模型： 服务器启动时接收一个根目录路径参数，所有文件操作都会被限制在该目录树下，防止 AI 访问敏感系统文件。

协议层： 通过 stdio 传输与 MCP 客户端通信，符合 MCP 规范定义的 JSON-RPC 2.0 消息格式，确保与所有兼容 MCP 的 AI 助手互操作。

维护者： 该项目托管在 modelcontextprotocol/servers GitHub 仓库，由 Anthropic 工程师和社区共同维护，是 MCP 官方案例和最权威的参考实现。

官方链接

• npm：https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem
• GitHub：https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem
• MCP 官方文档：https://modelcontextprotocol.io