Filesystem MCP Server已精选

什么是 Filesystem MCP Server？

Filesystem MCP Server 是 Model Context Protocol 项目提供的参考版 filesystem MCP 服务器：一个 Node.js 服务器，让 Claude 和其他 MCP 客户端可以读取、写入、编辑、移动和搜索文件，但只限于你允许的目录。

它在 npm 上以 @modelcontextprotocol/server-filesystem 发布，Docker 镜像为 mcp/filesystem，源码位于官方 modelcontextprotocol/servers 仓库（MIT License）。它通过 stdio 在本地运行，不需要 API key，并且每个工具都被标注为不会访问互联网或其他外部系统。

如何使用 Filesystem MCP Server？

前置条件：Node.js（用于 npx）或 Docker。无需账号或 API key。唯一必需的输入是至少一个允许访问的目录，可以通过命令行参数提供，也可以由客户端通过 MCP Roots 提供。

以命令行参数指定允许的目录：

mcp-server-filesystem /path/to/dir1 /path/to/dir2

推荐使用 MCP Roots：支持 Roots 的客户端会把工作区文件夹发送给服务器，服务器用它们替换命令行中的目录列表，并在运行时通过 roots/list_changed 接收变更，无需重启。

Claude Desktop

在 claude_desktop_config.json 中添加以下内容，并列出要开放的文件夹：

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

在 Windows 上，通过 cmd /c 启动 npx：

{
  "mcpServers": {
    "filesystem": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/path/to/other/allowed/dir"
      ]
    }
  }
}

使用 Docker 时，把每个目录挂载到 /projects 下。加上 ro 后，该挂载对服务器只读：

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount", "type=bind,src=/Users/username/Desktop,dst=/projects/Desktop",
        "--mount", "type=bind,src=/path/to/other/allowed/dir,dst=/projects/other/allowed/dir,ro",
        "mcp/filesystem",
        "/projects"
      ]
    }
  }
}

VS Code

在命令面板中运行 MCP: Open User Configuration，或在工作区中创建 .vscode/mcp.json 以便与他人共享配置。注意 VS Code 使用的是 servers 键：

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${workspaceFolder}"
      ]
    }
  }
}

Docker 版本会把 ${workspaceFolder} 挂载到 /projects/workspace，并把 /projects 作为参数传入。

Claude Code and Cursor

README 没有为这两个客户端提供步骤，但它们都可以运行同样的 stdio 命令。在 Claude Code 中：

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/dir

在 Cursor 中，把上面 Claude Desktop 的 mcpServers 配置块添加到 Cursor 的 mcp.json。

Filesystem MCP Server 的主要功能

• 沙箱访问：所有操作都限制在允许的目录内，list_allowed_directories 可显示当前生效的目录。
• 通过 MCP Roots 实现动态访问控制，允许的文件夹会跟随客户端工作区变化，无需重启。
• 文本与媒体读取：read_text_file 支持 head/tail 行数限制，read_media_file 以 base64 内容块返回图片和音频，并附带 MIME 类型。
• 安全编辑：edit_file 进行定点查找替换，保留缩进和 LF/CRLF 换行符，返回 git 风格的 diff，并支持 dryRun 预览。
• glob 风格搜索和递归 JSON directory_tree，两者都支持排除模式。
• MCP 工具注解会把每个工具标为只读、幂等或破坏性操作，客户端可以在高风险写入前请求确认。
• Docker 只读挂载（ro），用于模型可以读取但不能修改的文件夹。

Filesystem MCP Server 工具

该服务器提供 13 个工具，分为三组：

• 读取： read_text_file、read_media_file 和 read_multiple_files（单个读取失败不会中断整批操作）。
• 浏览与搜索： list_directory、list_directory_with_sizes（可按名称或大小排序，并给出汇总）、directory_tree、search_files、get_file_info（大小、时间、类型、权限）和 list_allowed_directories。
• 写入： write_file 创建或覆盖文件，edit_file 进行选择性编辑，create_directory 创建嵌套文件夹，move_file 移动或重命名文件，目标已存在时会失败。

没有删除工具。README 将 write_file、edit_file 和 move_file 标为破坏性操作。

Filesystem MCP Server 的使用场景

• 编辑项目文件夹中的代码或文档：“在 ~/projects/site 中，把 src 里所有 getUser 调用改名为 fetchUser，先给我看 diff。”
• 审阅文件夹：“列出 ~/Downloads 里最大的文件，并告诉我它们是什么。”
• 整理文件：“在 ~/Documents/invoices 中按年份建文件夹，把每个 PDF 移到对应的文件夹。”
• 读取图片进行分析：“打开 ~/Desktop/bug.png 截图，描述其中的错误。”
• 查找文件：“在 ~/notes 中搜索关于 Kubernetes 的 Markdown 文件，排除 archive 文件夹。”
• 搭建 MCP file system 沙箱：为聊天应用提供回答本地文件相关问题所需的只读上下文。

Filesystem MCP Server 与替代方案对比

• 内置文件工具： Claude Code 等编程智能体本身就能读取和编辑工作目录中的文件，因此这个 filesystem MCP 更适合 Claude Desktop 这类自身没有本地文件访问能力的聊天客户端，或者需要严格沙箱的场景。
• Desktop Commander： 一个社区 Node.js MCP 服务器，还能运行终端命令和管理进程。它的能力更广，因此风险也高于只处理文件的服务器。
• Memory MCP Server (Knowledge Graph)： 另一个参考服务器，用于跨对话保存持久事实，而不是访问文件。两者经常一起安装。

Filesystem MCP Server 常见问题排查

• 服务器启动时以状态码 1 退出： 启动时没有目录参数，而客户端又不支持 Roots。请在 args 中至少添加一个允许的目录。
• “Access denied - no allowed directories”： 客户端的 roots 被撤回或不包含有效路径。请在客户端中打开一个工作区文件夹，或添加命令行目录。
• 沙箱外的路径被拒绝： 这是设计行为。调用 list_allowed_directories 查看当前列表，并注意 Roots 会完全替换命令行目录。
• Docker 看不到你的文件： 默认情况下每个目录都必须挂载到 /projects 下，并且如 README 示例所示，/projects 作为目录参数传给服务器。
• Windows 上找不到 npx： 使用上面所示的 cmd /c npx ... 写法。