Filesystem MCP Server

文件系统 MCP 服务器

Node.js 服务器为文件系统操作实现模型上下文协议 (MCP)，具有全面的权限控制和增强的功能。

特征

• 细粒度的权限控制（只读、完全访问或特定操作权限）
• 在允许的目录内进行安全文件操作
• 文件操作：
  • 读/写/修改文件
  • 创建/列出/删除目录
  • 移动文件/目录
  • 按名称或扩展名搜索文件
  • 获取文件元数据
• 目录操作：
  • 目录结构的树状视图
  • 具有排除模式的递归操作
• 实用功能：
  • XML 到 JSON 的转换
  • 一次调用即可进行多个文件操作
  • 使用模式匹配进行高级文件编辑
• 安全功能：
  • 符号链接控制
  • 路径验证
  • 沙盒操作

注意：服务器只允许在通过args指定的目录内并根据配置的权限进行操作。

API

资源

• file://system ：文件系统操作接口

工具

• 读取文件
  • 读取文件的完整内容
  • 输入： path （字符串）
  • 使用 UTF-8 编码读取完整的文件内容
• 读取多个文件
  • 同时读取多个文件
  • 输入： paths （字符串[]）
  • 读取失败不会停止整个操作
• 创建文件
  • 创建包含内容的新文件
  • 输入：
    • path （字符串）：文件位置
    • content （字符串）：文件内容
  • 如果文件已存在则失败
  • 需要create权限
• 修改文件
  • 使用新内容修改现有文件
  • 输入：
    • path （字符串）：文件位置
    • content （字符串）：新文件内容
  • 如果文件不存在则失败
  • 需要edit权限
• 编辑文件
  • 使用模式匹配和格式进行选择性编辑
  • 特征：
    • 基于行和多行的内容匹配
    • 保留缩进的空白规范化
    • 多个同时编辑且定位正确
    • 缩进样式检测和保存
    • 带有上下文的 Git 风格差异输出
    • 使用试运行模式预览更改
  • 输入：
    • path （字符串）：要编辑的文件
    • edits （数组）：编辑操作列表
      • oldText （字符串）：要搜索的文本（完全匹配）
      • newText （字符串）：要替换的文本
    • dryRun （布尔值）：预览更改而不应用（默认值：false）
  • 返回试运行的详细差异，否则应用更改
  • 需要edit权限
  • 最佳实践：始终先使用 dryRun 来预览更改
• 创建目录
  • 创建新目录或确保其存在
  • 输入： path （字符串）
  • 如果需要，创建父目录
  • 如果目录存在，则静默成功
  • 需要create权限
• 列表目录
  • 列出带有 [FILE] 或 [DIR] 前缀的目录内容
  • 输入： path （字符串）
  • 返回文件和目录的详细列表
• 目录树
  • 获取目录结构的递归树视图
  • 输入： path （字符串）
  • 返回包含文件和目录的 JSON 结构
  • 每个条目包括名称、类型和子项（对于目录）
• 移动文件
  • 移动或重命名文件和目录
  • 输入：
    • source （字符串）：源路径
    • destination （字符串）：目标路径
  • 如果目标存在则失败
  • 适用于文件和目录
  • 需要move权限
• 删除文件
  • 删除文件
  • 输入： path （字符串）
  • 如果文件不存在则失败
  • 需要delete权限
• 删除目录
  • 删除目录
  • 输入：
    • path （字符串）：要删除的目录
    • recursive （布尔值）：是否删除内容（默认值：false）
  • 如果目录不为空并且递归为假，则失败
  • 需要delete权限
• 搜索文件
  • 递归搜索文件/目录
  • 输入：
    • path （字符串）：起始目录
    • pattern （字符串）：��索模式
    • excludePatterns (string[]): 排除模式（支持 glob 格式）
  • 不区分大小写的匹配
  • 返回匹配的完整路径
• 通过扩展名查找文件
  • 查找具有特定扩展名的所有文件
  • 输入：
    • path （字符串）：起始目录
    • extension （字符串）：要查找的文件扩展名
    • excludePatterns （string[]）：可选的排除模式
  • 不区分大小写的扩展匹配
  • 返回匹配文件的完整路径
• 获取文件信息
  • 获取详细的文件/目录元数据
  • 输入： path （字符串）
  • 返回：
    • 尺寸
    • 创建时间
    • 修改时间
    • 访问时间
    • 类型（文件/目录）
    • 权限
• 获取权限
  • 获取当前服务器权限
  • 无需输入
  • 返回：
    • 权限标志（只读、完全访问、创建、编辑、移动、删除）
    • 符号链接跟踪状态
    • 允许的目录数量
• 列出允许的目录
  • 列出服务器允许访问的所有目录
  • 无需输入
  • 返回允许的目录路径数组
• xml_to_json
  • 将 XML 文件转换为 JSON 格式
  • 输入：
    • xmlPath （字符串）：源 XML 文件
    • jsonPath （字符串）：目标 JSON 文件
    • options （对象）：可选设置
      • ignoreAttributes （布尔值）：跳过 XML 属性（默认值：false）
      • preserveOrder （布尔值）：保持属性顺序（默认值：true）
      • format （布尔值）：漂亮的打印 JSON（默认值：true）
      • indentSize （数字）：JSON 缩进（默认值：2）
  • 需要 XML 文件的read权限
  • 需要create或edit JSON 文件的权限
• xml_to_json_string
  • 将 XML 文件转换为 JSON 字符串
  • 输入：
    • xmlPath （字符串）：源 XML 文件
    • options （对象）：可选设置
      • ignoreAttributes （布尔值）：跳过 XML 属性（默认值：false）
      • preserveOrder （布尔值）：保持属性顺序（默认值：true）
  • 需要 XML 文件的read权限
  • 返回 JSON 字符串表示形式
• xml_查询
  • 使用 XPath 表达式查询 XML 文件
  • 输入：
    • path （字符串）：XML 文件的路径
    • query （字符串，可选）：要执行的 XPath 查询
    • structureOnly （布尔值，可选）：仅返回标签结构
    • maxBytes （数字，可选）：读取的最大字节数（默认值：1MB）
    • includeAttributes （布尔值，可选）：包含属性信息（默认值：true）
  • XPath 示例：
    • 获取所有元素： //tagname
    • 获取具有特定属性的元素： //tagname[@attr="value"]
    • 获取文本内容： //tagname/text()
  • 为大型 XML 文件节省内存
  • 返回查询结果或结构的 JSON 表示形式
• xml_结构
  • 无需读取整个文件即可分析 XML 结构
  • 输入：
    • path （字符串）：XML 文件的路径
    • depth （数字，可选）：分析深度（默认值：2）
    • includeAttributes （boolean，可选）：包含属性分析
    • maxBytes （数字，可选）：读取的最大字节数（默认值：1MB）
  • 返回有关元素、属性和结构的统计信息
  • 有助于在详细分析之前理解大型 XML 文件

权限和安全

服务器实现了具有细粒度权限控制的全面安全模型：

目录访问控制

• 操作严格限制在启动期间通过args指定的目录中
• 所有操作（包括符号链接目标）必须保留在允许的目录内
• 路径验证确保不会遍历目录或访问允许路径之外的内容

权限标志

• --readonly ：强制只读模式，覆盖所有其他权限标志
• –full-access ：启用所有操作（创建、编辑、移动、删除）
• 单独的权限标志（除非设置了--full-access，否则需要明确启用）：
  • –allow-create ：允许创建新文件和目录
  • –allow-edit ：允许修改现有文件
  • –allow-move ：允许移动/重命名文件和目录
  • –allow-delete ：允许删除文件和目录

默认行为：如果未指定权限标志，服务器将以只读模式运行。要启用任何写入操作，必须使用--full-access或特定的--allow-*标志。

符号链接处理

• 默认情况下，遵循符号链接（链接和目标都必须位于允许的目录中）
• –no-follow-symlinks ：禁用符号链接跟踪（操作作用于链接本身）

与 Claude Desktop 和 Cursor 一起使用

将适当的配置添加到claude_desktop_config.json (对于 Claude Desktop) 或.cursor/mcp.json (对于 Cursor)：

游标配置

在.cursor/mcp.json中：

Docker 配置

对于带有 Docker 的 Claude Desktop：

NPX 配置

对于 Claude Desktop 或带有 NPX 的 Cursor：

权限标志示例

您可以使用各种权限组合来配置服务器：

注意： --readonly优先于所有其他权限标志，并且--full-access启用所有操作，除非指定了--readonly 。

多个目录和权限

当指定多个目录时，权限标志全局应用于所有目录：

如果需要对不同的目录使用不同的权限级别，请创建多个服务器配置：

命令行示例

1. 只读访问权限：

2. 完全访问权限：

3. 具体权限：

4. 没有以下符号链接：

建造

Docker 构建：

执照

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