Filesystem

文件系统 MCP 服务

使用 Node.js 实现的文件系统操作模型上下文协议（MCP）服务。

已在 npm 上发布为 @modelcontextprotocol/server-filesystem。

功能

• 读写文件
• 创建、列出和删除目录
• 移动文件和目录
• 搜索文件
• 获取文件元数据
• 通过命令行参数控制目录访问；Roots 仅作为已弃用的 2025 年时代便捷功能
• 通过 stdio 同时支持两个协议时代：2026-07-28 客户端（server/discover，无握手）和 2025 年时代客户端（initialize）

目录访问控制

服务只能访问其允许的目录。通过命令行传入这些目录。支持 Roots 的 2025 年时代客户端也可以在运行时替换这些目录，但 Roots 已于协议版本 2026-07-28 中弃用，且 2026-07-28 连接无法使用它。

方法 1：命令行参数（推荐）

启动服务时指定允许的目录：

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

这是唯一适用于所有协议版本的方法，因此应优先使用。

方法 2：MCP Roots（已弃用，仅适用于 2025 年时代客户端）

使用 2025 年时代协议版本（initialize 握手）连接并支持 Roots 的客户端，可以动态更新允许的目录。

客户端通知服务的 Roots 会完全替换服务端的任何允许目录。

重要：如果服务在未指定命令行参数的情况下启动，且 2025 年时代客户端不支持 roots 协议，服务会在初始化时失败：它会将原因记录到 stderr，关闭连接并以状态码 1 退出。支持 roots 但未提供任何 root（或未提供有效 root）的客户端会保持连接，但在发送包含有效 root 的 roots/list_changed 之前，不会有任何允许的目录。

2026-07-28 协议没有 initialize 握手，也没有服务端到客户端的 roots/list 请求，因此不会向 2026-07-28 客户端请求其 roots：命令行目录就是全部允许列表。以未指定目录的方式启动的服务，在此类连接上会对每次工具调用都返回错误，说明没有允许的目录。

工作原理

服务的目录访问控制遵循以下流程：

1. 服务启动

   • 服务使用命令行参数中的目录启动（如果提供）
   • 如果未提供参数，服务将以空的允许目录列表启动

2. 客户端连接

   • 客户端的第一条消息决定连接所使用的协议版本
   • 2026-07-28 客户端发送 server/discover（或任何携带每个请求的 _meta 信封的请求）：服务使用命令行目录，第 3 步和第 4 步不适用
   • 2025-era 客户端发送包含其能力的 initialize，服务会检查其是否支持 roots（capabilities.roots）

3. Roots 协议处理（支持 roots 的 2025-era 客户端）

   • 初始化时：服务通过 roots/list 向客户端请求 roots
   • 客户端返回其配置的 roots
   • 服务将所有允许目录替换为客户端的 roots
   • 初始 roots 加载完成前到达的工具调用会等待加载完成，因此会依据客户端的 roots 进行检查
   • 运行时更新时：客户端可以发送 notifications/roots/list_changed
   • 服务请求更新后的 roots，并再次替换允许目录
   • 获取更新期间到达的工具调用会等待更新完成，因此不会有任何调用在客户端刚撤回的 root 下运行
   • 客户端的 roots 生效后，如果更新中没有有效 roots，就会撤销访问权限：所有路径都会被拒绝（“Access denied - no allowed directories”），直到客户端重新提供 root。在任何 root 尚未生效之前，此类更新会保留命令行目录

4. 回退行为（不支持 roots 的 2025-era 客户端）

   • 服务仅继续使用命令行目录
   • 无法进行动态更新
   • 如果也没有命令行目录，服务会记录错误、关闭连接并以状态码 1 退出

5. 访问控制

   • 所有文件系统操作都限制在允许目录内
   • 使用 list_allowed_directories 工具查看当前目录
   • 服务至少需要一个允许目录才能运行

注意：服务只允许在通过 args 指定的目录内操作，或者对于 2025-era 客户端，在通过 Roots 指定的目录内操作。

API

工具

• read_text_file

  • 以文本形式读取文件的完整内容
  • 输入：
    • path（字符串）
    • head（数字，可选）：前 N 行
    • tail（数字，可选）：后 N 行
  • 无论文件扩展名是什么，始终将文件视为 UTF-8 文本
  • 不能同时指定 head 和 tail

• read_media_file

  • 读取文件，并以带有其 MIME 类型的 Base64 编码内容块形式返回
  • 输入：
    • path（字符串）
  • 流式读取文件，并返回带有相应 MIME 类型的 Base64 数据。图像和 音频文件将作为 image/audio 内容返回；其他任何文件类型都将作为 嵌入式 resource 返回（适用于任意二进制数据的有效 MCP 内容块）

• read_multiple_files

  • 同时读取多个文件
  • 输入：paths（字符串数组）
  • 读取失败不会中止整个操作

• write_file

  • 创建新文件或覆盖现有文件（请谨慎操作）
  • 输入：
    • path（字符串）：文件位置
    • content（字符串）：文件内容
  • 现有文件会在原位置被覆盖，因此其 inode、创建时间、 硬链接和权限都会保留（edit_file 也以相同方式写入）。覆盖操作并非崩溃原子操作：如果在写入过程中发生崩溃，文件可能会只写入一部分。只读文件会被拒绝，而不会被替换

• edit_file

  • 使用高级模式匹配和格式处理进行选择性编辑
  • 特性：
    • 按行和多行内容匹配
    • 规范化空白字符，同时保留缩进
    • 同时进行多项编辑，并确保位置正确
    • 检测并保留缩进样式：仅空白字符不同时，每个替换行都会采用被替换行的缩进
    • 保留文件的换行符（LF 或 CRLF）
    • 输出带上下文的 Git 风格差异
    • 使用试运行模式预览更改
  • 输入：
    • path（字符串）：要编辑的文件
    • edits（数组）：编辑操作列表
      • oldText（字符串）：要搜索的文本（可以是子字符串）
      • newText（字符串）：替换文本
    • dryRun（布尔值）：预览更改但不应用（默认值：false）
  • 试运行时返回详细的差异和匹配信息，否则应用更改
  • 最佳实践：始终先使用 dryRun 预览更改，再应用更改

• create_directory

  • 创建新目录或确保目录存在
  • 输入：path（字符串）
  • 如有需要，创建父目录
  • 如果目录已存在，则静默成功

• list_directory

  • 使用 [FILE] 或 [DIR] 前缀列出目录内容
  • 输入：path（字符串）

• list_directory_with_sizes

  • 使用 [FILE] 或 [DIR] 前缀列出目录内容，并显示文件大小
  • 输入：
    • path（字符串）：要列出的目录路径
    • sortBy（字符串，可选）：按 "name" 或 "size" 对条目排序（默认值："name"）
  • 返回包含文件大小和统计摘要的详细列表
  • 显示文件总数、目录总数和合计大小

• move_file

  • 移动或重命名文件和目录
  • 输入：
    • source（字符串）
    • destination（字符串）
  • 如果目标已存在，则操作失败

• search_files

  • 递归搜索符合或不符合指定模式的文件/目录
  • 输入：
    • path（字符串）：起始目录
    • pattern（字符串）：搜索模式
    • excludePatterns（字符串[]）：排除符合指定模式的条目。
  • 支持 Glob 风格的模式匹配
  • 返回匹配项的完整路径

• directory_tree

  • 获取目录内容的递归 JSON 树结构
  • 输入：
    • path（字符串）：起始目录
    • excludePatterns（字符串[]）：排除符合指定模式的条目。支持 Glob 格式。
  • 返回：
    • JSON 数组，其中每个条目包含：
      • name（字符串）：文件/目录名称
      • type（'file'|'directory'）：条目类型
      • children（数组）：仅目录包含此字段
        • 空目录对应空数组
        • 文件不包含此字段
  • 输出采用 2 个空格缩进，便于阅读

• get_file_info

  • 获取文件/目录的详细元数据
  • 输入：path（字符串）
  • 返回：
    • 大小
    • 创建时间
    • 修改时间
    • 访问时间
    • 类型（文件/目录）
    • 权限

• list_allowed_directories

  • 列出服务获准访问的所有目录
  • 无需输入
  • 返回：
    • 此服务可读写的目录

工具注解（MCP 提示）

此服务会为每个工具设置 MCP ToolAnnotations， 以便客户端：

• 区分只读工具和可写入工具。
• 了解哪些写入操作是幂等的（使用相同参数重试是安全的）。
• 标示可能具有破坏性的操作（会覆盖或大幅修改数据）。
• 表明工具不会触及开放或外部世界（每个文件系统工具都设置了 openWorldHint: false）。

文件系统工具的映射如下：

工具	readOnlyHint	idempotentHint	destructiveHint	说明
read_text_file	true	–	–	纯读取
read_media_file	true	–	–	纯读取
read_multiple_files	true	–	–	纯读取
list_directory	true	–	–	纯读取
list_directory_with_sizes	true	–	–	纯读取
directory_tree	true	–	–	纯读取
search_files	true	–	–	纯读取
get_file_info	true	–	–	纯读取
list_allowed_directories	true	–	–	纯读取
create_directory	false	true	false	重复创建同一目录不会产生任何影响
write_file	false	true	true	覆盖现有文件
edit_file	false	false	true	重新应用编辑可能失败或重复应用
move_file	false	false	true	删除源文件

注意：根据 MCP 规范，只有当 readOnlyHint 为 false 时，idempotentHint 和 destructiveHint 才有意义。每个工具也都设置了 openWorldHint: false——此服务仅访问其允许目录中的本地文件系统，不会触及开放或外部世界。

要求

通过 npx 运行服务器或从源码运行时，需要 Node.js 24 或更高版本。

在 Claude Desktop 中使用

将以下内容添加到 claude_desktop_config.json：

注意：你可以将沙盒目录挂载到 /projects，以便服务器访问这些目录。添加 ro 标志会使服务器只能以只读方式访问该目录。

Docker

注意：默认情况下，所有目录都必须挂载到 /projects。

{
  "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",
        "--mount", "type=bind,src=/path/to/file.txt,dst=/projects/path/to/file.txt",
        "mcp/filesystem",
        "/projects"
      ]
    }
  }
}

NPX

{
  "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"
      ]
    }
  }
}

在 VS Code 中使用

如需快速安装，请点击下方的安装按钮……

如需手动安装，可以通过以下任一方式配置 MCP 服务：

方法 1：用户配置（推荐） 将配置添加到用户级 MCP 配置文件中。打开命令面板（Ctrl + Shift + P），并运行 MCP: Open User Configuration。这会打开用户的 mcp.json 文件，你可以在其中添加服务配置。

方法 2：工作区配置 或者，你也可以在工作区中创建名为 .vscode/mcp.json 的文件，并将配置添加到其中。这样便可以与他人共享配置。

有关 VS Code 中 MCP 配置的更多详情，请参阅 VS Code 官方 MCP 文档。

你可以将沙盒目录挂载到 /projects，以便提供给服务。添加 ro 标志会使服务只能以只读方式访问该目录。

Docker

注意：默认情况下，所有目录都必须挂载到 /projects。

{
  "servers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount", "type=bind,src=${workspaceFolder},dst=/projects/workspace",
        "mcp/filesystem",
        "/projects"
      ]
    }
  }
}

NPX

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

在 Windows 上，请使用：

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

构建

Docker 构建：

docker build -t mcp/filesystem -f src/filesystem/Dockerfile .

许可证

此 MCP 服务采用 MIT 许可证。这意味着你可以自由使用、修改和分发本软件，但须遵守 MIT 许可证的条款和条件。更多详情请参阅项目仓库中的 LICENSE 文件。