AI导哈

文件系统操作服务器

基于Model Context Protocol (MCP)的Node.js文件系统操作服务器，提供文件读写、目录管理、搜索及动态访问控制功能，适用于开发环境集成和自动化文件处理场景。

  • by danny-avila
  • TypeScript
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 danny-avila/server-filesystem

使用说明

文件系统MCP服务器

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

特性

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

目录访问控制

服务器使用灵活的目录访问控制系统。目录可以通过命令行参数指定，也可以通过以下方式动态指定 根.

方法1：命令行参数

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

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

方法2:MCP根（推荐）

支持的MCP客户端 根 可以动态更新Allowed目录。

客户端通知服务器的根目录，在提供时完全替换任何服务器端允许的目录。

重要：如果服务器在没有命令行参数的情况下启动，并且客户端不支持根协议（或提供空根），则服务器将在初始化过程中抛出错误。

这是推荐的方法，因为这可以通过以下方式实现运行时目录更新 roots/list_changed 无需重新启动服务器即可发出通知，提供更灵活、更现代的集成体验。

运作原理

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

  1. 服务器启动

    • 服务器从命令行参数（如果提供）中的目录开始
    • 如果没有提供参数，服务器将从允许的空目录开始

  2. 客户端连接和初始化

    • 客户端连接并发送 initialize 具有能力的请求
    • 服务器检查客户端是否支持根协议(capabilities.roots)

  3. 根协议处理 （如果客户端支持root）

    • 初始化时：服务器通过从客户端请求根 roots/list
    • 客户端使用其配置的根进行响应
    • 服务器将所有允许的目录替换为客户端的根目录
    • 运行时更新：客户端可以发送 notifications/roots/list_changed
    • 服务器请求更新根目录并再次替换允许的目录

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

    • 服务器仅继续使用命令行目录
    • 无法进行动态更新

  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数据

  • 读取多个文件

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

  • write_file

    • 创建新文件或覆盖现有文件（请谨慎操作）
    • 输入：
      • path （string）：文件位置
      • content （string）：文件内容

  • edit_file

    • 使用高级模式匹配和格式进行选择性编辑
    • 特征：
      • 基于行和多行内容匹配
      • 保留缩进的空白归一化
      • 具有正确定位的多个同时编辑
      • 压痕样式检测和保存
      • 带上下文的Git风格差异输出
      • 使用模拟运行模式预览更改
    • 输入：
      • path （string）：要编辑的文件
      • edits （array）：编辑操作列表
        • oldText （string）：要搜索的文本（可以是子字符串）
        • newText （string）：要替换的文本
      • dryRun （boolean）：预览更改而不应用（默认值：false）
    • 返回模拟运行的详细差异和匹配信息，否则应用更改
    • 最佳实践：在应用更改之前，始终先使用dryRun预览更改

  • create_directory

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

  • list_directory

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

  • list_directory_with_sizes

    • 列出带有[FILE]或[DIR]前缀的目录内容，包括文件大小
    • 输入：
      • path （string）：列表的目录路径
      • sortBy （字符串，可选）：按“名称”或“大小”对条目进行排序（默认值：“名称”）
    • 返回包含文件大小和摘要统计信息的详细列表
    • 显示总文件、目录和组合大小

  • move_file

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

  • 搜索文件

    • 递归搜索匹配或不匹配模式的文件/目录
    • 输入：
      • path （string）：起始目录
      • pattern （string）：搜索模式
      • excludePatterns （string[]）：排除任何模式。
    • 环球风格图案搭配
    • 返回匹配项的完整路径

  • 目录树

    • 获取目录内容的递归JSON树结构
    • 输入：
      • path （string）：起始目录
      • excludePatterns （string[]）：排除任何模式。支持Glob格式。
    • 退货：
      • JSON数组，其中每个条目包含：
        • name （string）：文件/目录名
        • type （“文件”|“目录”）：条目类型
        • children （array）：仅适用于目录
          • 空目录的空数组
          • 文件省略
    • 为了提高可读性，输出采用2空格缩进格式

  • 获取_文件_信息

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

  • list_allowed_directories

    • 列出服务器允许访问的所有目录
    • 无需输入
    • 退货：
      • 此服务器可以读取/写入的目录

使用Claude Desktop

将此添加到您的 claude_desktop_config.json:

注意：您可以通过将沙盒目录挂载到以下位置来向服务器提供沙盒目录 /projects.添加 ro 标志将使目录对服务器只读。

码头工人

注意：所有目录都必须挂载到 /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代码

要快速安装，请单击下面的安装按钮。..

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

方法1：用户配置（推荐） 将配置添加到用户级MCP配置文件中。打开命令选项板(Ctrl + Shift + P)然后跑 MCP: Open User Configuration。这将打开您的用户 mcp.json 您可以在其中添加服务器配置的文件。

方法2：工作空间配置 或者，您可以将配置添加到名为的文件中 .vscode/mcp.json 在您的工作空间中。这将允许您与他人共享配置。

有关VS Code中MCP配置的更多详细信息，请参阅 官方VS Code MCP文档.

您可以通过将沙盒目录挂载到以下位置来向服务器提供沙盒目录 /projects.添加 ro 标志将使目录对服务器只读。

码头工人

注意：所有目录都必须挂载到 /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文件。

相关 MCP