星战科技xingzhan.cloud
返回市场
文件系统

文件系统

作者：modelcontextprotocol73187 星标更新：2025-11-23
安装使用来源：spider==github.com

项目介绍

技术文档摘要

文件系统 MCP 服务器

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

功能

  • 读写文件
  • 创建、列出、删除目录
  • 移动文件/目录
  • 搜索文件
  • 获取文件元数据
  • 通过 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

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

  • 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

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

在 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 中使用

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

在 VS Code 中使用 NPX 安装 在 VS Code Insiders 中使用 NPX 安装

在 VS Code 中使用 Docker 安装 在 VS Code Insiders 中使用 Docker 安装

对于手动安装，您可以使用以下方法之一配置 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 文件。

文件系统 - MCP 市场 - 星战科技