文件系统 MCP 服务器

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

特性

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

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

API

资源

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

工具

• read_file

  • 读取文件的完整内容
  • 输入: path (字符串)
  • 以 UTF-8 编码读取整个文件的内容

• read_multiple_files

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

• create_file

  • 创建带有内容的新文件
  • 输入:
    • path (字符串): 文件位置
    • content (字符串): 文件内容
  • 如果文件已存在则失败
  • 需要 create 权限

• modify_file

  • 用新内容修改现有文件
  • 输入:
    • path (字符串): 文件位置
    • content (字符串): 新文件内容
  • 如果文件不存在则失败
  • 需要 edit 权限

• edit_file

  • 使用模式匹配和格式化进行选择性编辑
  • 功能:
    • 基于行和多行内容匹配
    • 保留缩进的空白字符规范化
    • 正确定位的多次同时编辑
    • 识别并保留缩进风格
    • 具有上下文的 Git 风格差异输出
    • 通过预览模式查看更改而不应用
  • 输入:
    • path (字符串): 要编辑的文件
    • edits (数组): 编辑操作列表
      • oldText (字符串): 要查找的文本（精确匹配）
      • newText (字符串): 要替换为的文本
    • dryRun (布尔值): 预览更改而不应用（默认: false）
  • 返回详细的差异信息用于预览，否则应用更改
  • 需要 edit 权限
  • 最佳实践: 总是先使用 dryRun 预览更改

• create_directory

  • 创建新目录或确保其存在
  • 输入: path (字符串)
  • 如需要则创建父目录
  • 如果目录已存在则静默成功
  • 需要 create 权限

• list_directory

  • 列出目录内容，带有 [FILE] 或 [DIR] 前缀
  • 输入: path (字符串)
  • 返回文件和目录的详细列表

• directory_tree

  • 获取目录结构的递归树形视图
  • 输入: path (字符串)
  • 返回包含文件和目录的 JSON 结构
  • 每个条目包括名称、类型和子项（对于目录）

• move_file

  • 移动或重命名文件和目录
  • 输入:
    • source (字符串): 源路径
    • destination (字符串): 目标路径
  • 如果目标存在则失败
  • 适用于文件和目录
  • 需要 move 权限

• delete_file

  • 删除一个文件
  • 输入: path (字符串)
  • 如果文件不存在则失败
  • 需要 delete 权限

• delete_directory

  • 删除一个目录
  • 输入:
    • path (字符串): 要删除的目录
    • recursive (布尔值): 是否删除内容（默认: false）
  • 如果目录不为空且 recursive 为 false 则失败
  • 需要 delete 权限

• search_files

  • 递归搜索文件/目录
  • 输入:
    • path (字符串): 起始目录- find_files
  • 根据模式查找文件
  • 输入：
    • pattern (字符串): 搜索模式
    • excludePatterns (字符串[]): 排除模式（支持 glob 格式）
  • 不区分大小写的匹配
  • 返回匹配项的完整路径

• find_files_by_extension

  • 查找具有特定扩展名的所有文件
  • 输入：
    • path (字符串): 起始目录
    • extension (字符串): 要查找的文件扩展名
    • excludePatterns (字符串[], 可选): 排除模式
  • 不区分大小写的扩展名匹配
  • 返回匹配文件的完整路径

• get_file_info

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

• get_permissions

  • 获取当前服务器权限
  • 无需输入
  • 返回：
    • 权限标志 (readonly, fullAccess, create, edit, move, delete)
    • 符号链接跟随状态
    • 允许访问的目录数量

• list_allowed_directories

  • 列出服务器允许访问的所有目录
  • 无需输入
  • 返回允许访问的目录路径数组

• xml_to_json

  • 将 XML 文件转换为 JSON 格式
  • 输入：
    • xmlPath (字符串): 源 XML 文件
    • jsonPath (字符串): 目标 JSON 文件
    • options (对象): 可选设置
      • ignoreAttributes (布尔值): 跳过 XML 属性 (默认: false)
      • preserveOrder (布尔值): 保持属性顺序 (默认: true)
      • format (布尔值): 美化打印 JSON (默认: true)
      • indentSize (数字): JSON 缩进 (默认: 2)
  • 需要对 XML 文件的 read 权限
  • 需要对 JSON 文件的 create 或 edit 权限

• xml_to_json_string

  • 将 XML 文件转换为 JSON 字符串
  • 输入：
    • xmlPath (字符串): 源 XML 文件
    • options (对象): 可选设置
      • ignoreAttributes (布尔值): 跳过 XML 属性 (默认: false)
      • preserveOrder (布尔值): 保持属性顺序 (默认: true)
  • 需要对 XML 文件的 read 权限
  • 返回 JSON 字符串表示

• xml_query

  • 使用 XPath 表达式查询 XML 文件
  • 输入：
    • path (字符串): XML 文件的路径
    • query (字符串, 可选): 要执行的 XPath 查询
    • structureOnly (布尔值, 可选): 仅返回标签结构
    • maxBytes (数字, 可选): 最大读取字节数 (默认: 1MB)
    • includeAttributes (布尔值, 可选): 包含属性信息 (默认: true)
  • XPath 示例：
    • 获取所有元素: //tagname
    • 获取具有特定属性的元素: //tagname[@attr="value"]
    • 获取文本内容: //tagname/text()
  • 对大型 XML 文件内存效率高
  • 返回查询结果或结构的 JSON 表示

• xml_structure

  • 在不读取整个文件的情况下分析 XML 结构
  • 输入：
    • path (字符串): XML 文件的路径
    • depth (数字, 可选): 分析深度 (默认: 2)
    • includeAttributes (布尔值, 可选): 包含属性分析
    • 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 配置

在 .cursor/mcp.json 中：

json { "mcpServers": { "my-filesystem": { "command": "node", "args": [ "/path/to/mcp-filesystem/dist/index.js", "~/path/to/allowed/directory", "--full-access" ] } } }

Docker 配置

对于使用 Docker 的 Claude Desktop：

json { "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", "--readonly", // 用于只读访问 "--no-follow-symlinks", // 可选：防止符号链接跟随 "/projects" ] } } }

NPX 配置

对于使用 NPX 的 Claude Desktop 或 Cursor：

json { "mcpServers": { "filesystem": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-filesystem", "--full-access", // 用于完全读写访问 "/Users/username/Desktop", "/path/to/other/allowed/dir" ] } …