Filesystem MCP Server

文件系统 MCP 服务

用于文件系统操作的安全、单二进制 MCP 服务。无需运行时依赖——下载后配置允许访问的目录，即可连接到任意 MCP 客户端。

已在真实编码工作流中与 Claude Desktop 和 Claude Code 进行了广泛测试，涵盖文件编辑、代码库搜索、重构和多文件批量操作。

为什么选择此服务？

• 单个二进制文件 — 无需 Node.js、Python 或其他运行时。下载后即可运行
• 经过真实 AI 工作流测试 — 已通过 Claude Desktop 和 Claude Code 在日常编码任务中实战验证
• 18 个工具 — 不止于基础读写，还支持正则表达式搜索、基于模式的替换、自动缩进的代码插入和批量操作
• 试运行预览 — 替换和插入工具可在应用更改前预览结果
• 默认安全 — 沙箱限制在已配置的目录内，并提供符号链接攻击防护和路径遍历防护
• 详细错误消息 — 访问被拒绝时，错误会说明原因并提供修复建议

安装

下载发行版二进制文件

从 Releases 页面下载适用于你平台的最新二进制文件：

平台	二进制文件
macOS（Apple Silicon）	filesystem-mcp-darwin-arm64
macOS（Intel）	filesystem-mcp-darwin-amd64
Linux（x86_64）	filesystem-mcp-linux-amd64
Linux（ARM64）	filesystem-mcp-linux-arm64
Windows	filesystem-mcp-windows-amd64.exe

赋予其可执行权限（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 许可证