Filesystem MCP Server

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

已发布到 npm，包名为 @modelcontextprotocol/server-filesystem。

功能

• 读取/写入文件

• 创建/列出/删除目录

• 移动文件/目录

• 搜索文件

• 获取文件元数据

• 通过 Roots 实现动态目录访问控制

目录访问控制

服务器使用灵活的目录访问控制系统。可以通过命令行参数或通过 Roots 动态指定目录。

方法 1：命令行参数

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

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

方法 2：MCP Roots（推荐）

支持 Roots 的 MCP 客户端可以动态更新允许的目录。

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

重要：如果服务器启动时没有命令行参数，并且客户端不支持 roots 协议（或提供空的 roots），服务器将在初始化期间抛出错误。

这是推荐的方法，因为它允许通过 roots/list_changed 通知在运行时更新目录，无需重启服务器，从而提供更灵活、更现代的集成体验。

工作原理

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

1. 服务器启动

   • 服务器从命令行参数（如果提供）获取目录

   • 如果没有提供参数，服务器以空的允许目录启动

2. 客户端连接与初始化

   • 客户端连接并发送带有能力的 initialize 请求

   • 服务器检查客户端是否支持 roots 协议（capabilities.roots）

3. Roots 协议处理（如果客户端支持 roots）

   • 初始化时：服务器通过 roots/list 向客户端请求 roots

   • 客户端响应其配置的 roots

   • 服务器将所有允许的目录替换为客户端的 roots

   • 运行时更新：客户端可以发送 notifications/roots/list_changed

   • 服务器请求更新的 roots 并再次替换允许的目录

4. 回退行为（如果客户端不支持 roots）

   • 服务器仅继续使用命令行指定的目录

   • 无法进行动态更新

5. 访问控制

   • 所有文件系统操作仅限于允许的目录

   • 使用 list_allowed_directories 工具查看当前目录

   • 服务器需要至少一个允许的目录才能运行

注意：服务器只允许在通过 args 或 Roots 指定的目录内进行操作。

API

工具

• read_text_file

  • 以文本形式读取文件的完整内容

  • 输入：

    • path（字符串）

    • head（数字，可选）：前 N 行

    • tail（数字，可选）：后 N 行

  • 始终将文件视为 UTF-8 文本，无论扩展名如何

  • 不能同时指定 head 和 tail

• read_media_file

  • 读取文件并以 base64 编码的内容块及其 MIME 类型返回

  • 输入：

    • path（字符串）

  • 流式读取文件并返回 base64 数据及对应的 MIME 类型。图像和音频文件作为 image/audio 内容返回；其他任何文件类型作为嵌入的 resource（用于任意二进制数据的有效 MCP 内容块）返回

• read_multiple_files

  • 同时读取多个文件

  • 输入：paths（字符串数组）

  • 读取失败不会停止整个操作

• write_file

  • 创建新文件或覆盖现有文件（请谨慎使用）

  • 输入：

    • path（字符串）：文件位置

    • content（字符串）：文件内容

• edit_file

  • 使用高级模式匹配和格式化进行选择性编辑

  • 功能：

    • 基于行和多行的内容匹配

    • 空白规范化并保留缩进

    • 多个同时编辑，位置正确

    • 缩进样式检测和保留

    • 带上下文的 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）。

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

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

与 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 文件。