简介

此Node.js服务器实现了用于文件系统操作的模型上下文协议（MCP），包括读写文件、创建和列出目录、移动文件、搜索文件和获取文件元数据。它还支持通过Roots进行动态目录访问控制。

简介

此Node.js服务器实现了用于文件系统操作的模型上下文协议（MCP），包括读写文件、创建和列出目录、移动文件、搜索文件和获取文件元数据。它还支持通过Roots进行动态目录访问控制。

文件系统 MCP 服务器

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

功能

• 读写文件
• 创建/列出/删除目录
• 移动文件/目录
• 搜索文件
• 获取文件元数据
• 通过 Roots 动态目录访问控制

目录访问控制

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

方法 1：命令行参数

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

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

  • 读取图像或音频文件
  • 输入：
    • path (字符串)
  • 流式传输文件并返回带有相应 MIME 类型的 base64 数据

• read_multiple_files

  • 同时读取多个文件
  • 输入: paths (字符串数组)
  • 失败的读取不会停止整个操作

• write_file

  • 创建新文件或覆盖现有文件（谨慎使用此功能）
  • 输入：
    • path (字符串): 文件位置
    • content (字符串): 文件内容

• edit_file

  • 使用高级模式匹配和格式化进行选择性编辑
  • 特性：
    • 基于行和多行内容匹配
    • 保留缩进的空白字符规范化
    • 正确定位的多次同时编辑
    • 缩进样式检测和保留
    • 带有上下文的 Git 风格差异输出
    • 通过干运行模式预览更改
  • 输入：
    • path (字符串): 要编辑的文件
    • edits (数组): 编辑操作列表
      • oldText (字符串): 要搜索的文本（可以是子字符串）- newText (string): 要替换的文本

• dryRun (boolean): 预览更改而不实际应用（默认值：false）

  • 在预览模式下返回详细的差异和匹配信息，否则应用更改
  • 最佳实践：在应用更改之前始终先使用 dryRun 预览更改

• create_directory

  • 创建新目录或确保其存在
  • 输入: path (string)
  • 如果需要，会创建父目录
  • 如果目录已存在，则静默成功

• list_directory

  • 列出目录内容，并带有 [FILE] 或 [DIR] 前缀
  • 输入: path (string)

• list_directory_with_sizes

  • 列出目录内容，并带有 [FILE] 或 [DIR] 前缀，包括文件大小
  • 输入:
    • path (string): 要列出的目录路径
    • sortBy (string, 可选): 按 "name" 或 "size" 排序（默认值："name"）
  • 返回包含文件大小和汇总统计信息的详细列表
  • 显示总文件数、目录数和合计大小

• move_file

  • 移动或重命名文件和目录
  • 输入:
    • source (string)
    • destination (string)
  • 如果目标已存在则失败

• search_files

  • 递归搜索与模式匹配或不匹配的文件/目录
  • 输入:
    • path (string): 起始目录
    • pattern (string): 搜索模式
    • excludePatterns (string[]): 排除任何模式
  • 使用 glob 风格的模式匹配
  • 返回匹配项的完整路径

• directory_tree

  • 获取目录内容的递归 JSON 树结构
  • 输入:
    • path (string): 起始目录
    • excludePatterns (string[]): 排除任何模式。支持 glob 格式。
  • 返回:
    • JSON 数组，每个条目包含：
      • name (string): 文件/目录名称
      • type ('file'|'directory'): 条目类型
      • children (数组): 仅对目录有效
        • 空目录为空数组
        • 对于文件省略
  • 输出格式为 2 个空格缩进，以便于阅读

• get_file_info

  • 获取文件/目录的详细元数据
  • 输入: path (string)
  • 返回:
    • 大小
    • 创建时间
    • 修改时间
    • 访问时间
    • 类型 (file/directory)
    • 权限

• list_allowed_directories

  • 列出服务器允许访问的所有目录
  • 不需要输入
  • 返回:
    • 该服务器可以读写的所有目录

工具注释 (MCP 提示)

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

• 区分只读工具和可写工具。
• 了解哪些写操作是幂等的（使用相同参数重试是安全的）。
• 强调可能具有破坏性的操作（覆盖或大量修改数据）。

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

注意：idempotentHint 和 destructiveHint 只有在 readOnlyHint 为 false 时才有意义，这是由 MCP 规范定义的。

与 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"

      ]

    }

  }

}

与 VS Code 一起使用

快速安装，请点击下面的安装按钮...

手动安装时，您可以使用以下方法之一配置 MCP 服务器：

方法 1：用户配置（推荐） 将配置添加到您的用户级 MCP 配置文件中。打开命令面板 (Ctrl + Shift + P) 并运行 MCP: 打开用户配置。这将打开您的用户 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}"

      ]

    }

  }

}

构建

Docker 构建：

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

许可证此MCP服务器依据MIT许可证授权。这意味着您可以在遵守MIT许可证的条款和条件的前提下自由使用、修改和分发该软件。更多详情，请参阅项目仓库中的LICENSE文件。

工具列表

• read_file: Read the complete contents of a file as text. DEPRECATED: Use read_text_file instead.

• read_text_file: Read the complete contents of a file from the file system as text. Handles various text encodings and provides detailed error messages if the file cannot be read. Use this tool when you need to examine the contents of a single file. Use the 'head' parameter to read only the first N lines of a file, or the 'tail' parameter to read only the last N lines of a file. Operates on the file as text regardless of extension. Only works within allowed directories.

• read_media_file: Read an image or audio file. Returns the base64 encoded data and MIME type. Only works within allowed directories.

• read_multiple_files: Read the contents of multiple files simultaneously. This is more efficient than reading files one by one when you need to analyze or compare multiple files. Each file's content is returned with its path as a reference. Failed reads for individual files won't stop the entire operation. Only works within allowed directories.

• write_file: Create a new file or completely overwrite an existing file with new content. Use with caution as it will overwrite existing files without warning. Handles text content with proper encoding. Only works within allowed directories.

• edit_file: Make line-based edits to a text file. Each edit replaces exact line sequences with new content. Returns a git-style diff showing the changes made. Only works within allowed directories.

• create_directory: Create a new directory or ensure a directory exists. Can create multiple nested directories in one operation. If the directory already exists, this operation will succeed silently. Perfect for setting up directory structures for projects or ensuring required paths exist. Only works within allowed directories.

• list_directory: Get a detailed listing of all files and directories in a specified path. Results clearly distinguish between files and directories with [FILE] and [DIR] prefixes. This tool is essential for understanding directory structure and finding specific files within a directory. Only works within allowed directories.

• list_directory_with_sizes: Get a detailed listing of all files and directories in a specified path, including sizes. Results clearly distinguish between files and directories with [FILE] and [DIR] prefixes. This tool is useful for understanding directory structure and finding specific files within a directory. Only works within allowed directories.

• directory_tree: Get a recursive tree view of files and directories as a JSON structure. Each entry includes 'name', 'type' (file/directory), and 'children' for directories. Files have no children array, while directories always have a children array (which may be empty). The output is formatted with 2-space indentation for readability. Only works within allowed directories.

• move_file: Move or rename files and directories. Can move files between directories and rename them in a single operation. If the destination exists, the operation will fail. Works across different directories and can be used for simple renaming within the same directory. Both source and destination must be within allowed directories.

• search_files: Recursively search for files and directories matching a pattern. The patterns should be glob-style patterns that match paths relative to the working directory. Use pattern like '.ext' to match files in current directory, and '**/.ext' to match files in all subdirectories. Returns full paths to all matching items. Great for finding files when you don't know their exact location. Only searches within allowed directories.

• get_file_info: Retrieve detailed metadata about a file or directory. Returns comprehensive information including size, creation time, last modified time, permissions, and type. This tool is perfect for understanding file characteristics without reading the actual content. Only works within allowed directories.

• list_allowed_directories: Returns the list of directories that this server is allowed to access. Subdirectories within these allowed directories are also accessible. Use this to understand which directories and their nested paths are available before trying to access files.

服务配置

[{'mcpServers': {'filesystem': {'args': ['-y', '@modelcontextprotocol/server-filesystem', '/root'], 'command': 'npx'}}}]

来源

• 来源：github
• 链接：https://github.com/modelcontextprotocol/servers