文件系统 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"
]
}
}
}

权限标志示例

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

json
"args": [
"/path/to/mcp-filesystem/dist/index.js",
"~/path/to/allowed/directory",
"--readonly" // 只读模式
]

json
"args": [
"/path/to/mcp-filesystem/dist/index.js",
"~/path/to/allowed/directory",
"--full-access", // 完全读写访问
"--no-follow-symlinks" // 不跟随符号链接
]

json
"args": [
"/path/to/mcp-filesystem/dist/index.js",
"~/path/to/allowed/directory",
"--allow-create", // 选择性权限
"--allow-edit" // 仅允许创建和编辑
]

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

多个目录和权限

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

json
"args": [
"/path/to/mcp-filesystem/dist/index.js",
"~/first/directory", // 两个目录具有相同的
"~/second/directory", // 权限设置（只读）
"--readonly"
]

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

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

命令行示例

1. 只读访问：
   bash
   npx -y @modelcontextprotocol/server-filesystem --readonly /path/to/dir2. 完全访问权限：
   bash
   npx -y @modelcontextprotocol/server-filesystem --full-access /path/to/dir

2. 特定权限：
   bash
   npx -y @modelcontextprotocol/server-filesystem --allow-create --allow-edit /path/to/dir

3. 不跟随符号链接：
   bash
   npx -y @modelcontextprotocol/server-filesystem --full-access --no-follow-symlinks /path/to/dir

构建

Docker 构建：

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

许可证

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