文件系统操作服务器

文件系统MCP服务器

用于文件系统操作的安全的单二进制MCP服务器。无运行时依赖关系——下载、配置允许的目录并连接到任何MCP客户端。

使用Claude Desktop和Claude Code在真实世界的编码工作流程中进行了广泛的测试，包括文件编辑、代码库搜索、重构和多文件批处理操作。

为什么是这个服务器？

• 单个二进制 --不需要Node.js、Python或其他运行时。下载并运行
• 经过真实AI工作流程的测试 --使用Claude Desktop和Claude Code进行日常编码任务的战斗测试
• 18工具 --超越了使用正则表达式搜索、基于模式的替换、自动缩进代码插入和批处理操作的基本读/写
• 模拟运行预览 --在将更改应用于替换和插入工具之前预览更改
• 缺省安全 --沙盒到配置的目录，具有符号链接攻击防御和路径遍历保护
• 详细的错误消息 --当访问被拒绝时，错误会解释原因并建议修复

安装

下载发布二进制文件

从以下网址下载适用于您平台的最新二进制文件 发布 页面：

使其可执行（macOS/Linux）：

chmod +x filesystem-mcp-darwin-arm64

从源代码构建

go build -ldflags="-s -w" -o bin/filesystem-mcp ./cmd

配置

使用环境变量设置允许的目录：

export MCP_ALLOWED_DIRS="/path1,/path2,/path with spaces/dir3"

工具

阅读

• read_file --读取单个文件，可选 start_line/end_line 部分阅读
• read_multiple_files --在一次通话中同时读取多个文件
• search_in_files --递归正则表达式跨文件搜索。返回文件路径、行号和匹配的文本。自动跳过二进制文件。参数： path, pattern, file_extensions, max_results, case_sensitive

写作

• write_file --创建或覆盖文件。自动创建父目录
• append_to_file --将内容添加到文件末尾。如果文件不存在，则创建该文件
• prepend_to_file --将内容添加到文件开头。如果文件不存在，则创建该文件

文本替换

所有替换工具支持 dry_run 预览更改而不应用它们。

• replace_in_file --替换文件中出现的确切字符串。参数： path, search, replace, occurrence （0=全部）， dry_run
• replace_in_file_regex --用捕获组支持替换正则表达式模式匹配($1, $2).参数： path, pattern, replace, occurrence, case_sensitive, dry_run
• replace_in_files --批量替换多个文件中的字符串。在应用之前验证所有路径。参数： paths, search, replace, dry_run

基于正则表达式的插入

所有插入工具均支持 dry_run 和 autoIndent （与周围的缩进相匹配）。

• insert_after_regex --在正则表达式模式匹配后插入内容。参数： path, pattern, content, occurrence （0=全部，默认值1）， autoIndent, dry_run
• insert_before_regex --在正则表达式模式匹配之前插入内容。与上述参数相同

行复制

• copy_lines --将行范围从源文件直接复制到磁盘上的目标文件（无上下文开销）。参数： source_path, destination_path, start_line, end_line, append

目录操作

• list_directory --按模式、文件类型、递归深度、隐藏文件和元数据过滤列出目录内容。参数： path, pattern, file_type, recursive, max_depth, max_results, include_hidden, include_metadata
• create_directory --创建目录和父目录（幂等）
• list_allowed_directories --显示可访问的目录

文件管理

• move_file --移动或重命名文件和目录
• get_file_info --获取文件元数据（大小、权限、修改时间）

使用Claude Desktop

添加 claude_desktop_config.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "/path/to/filesystem-mcp-darwin-arm64",
      "env": {
        "MCP_ALLOWED_DIRS": "/path1,/path2,/path with spaces/dir3"
      }
    }
  }
}

安全

服务器实现了深度防御安全，以防止未经授权的文件访问。

路径验证

• 符号链接解析：所有路径通过解析为规范形式 filepath.EvalSymlinks() 验证前
• 路径遍历预防：块 ../ 逃跑企图
• 前缀匹配保护：使用路径分隔符进行验证，以防止 /allowed 匹配 /allowed_attacker

符号链接处理

• 如果允许目录中的符号链接的目标也在允许的目录中，则允许使用这些符号链接
• 指向允许目录之外的符号链接被阻止
• 断开的符号链接被拒绝
• 允许的目录本身可能是符号链接（在初始化过程中解析）

写入操作安全

• 验证父目录链以创建新文件
• 路径解析和验证以原子方式进行

安全日志

• 所有被阻止的访问尝试都会被记录 SECURITY: 前缀
• 日志包括请求的路径及其规范解析

最佳实践

• 配置 MCP_ALLOWED_DIRS 使用最少的必要目录
• 为允许的目录使用绝对路径
• 监控日志 SECURITY: 消息

许可证

MIT许可证