文件系统MCP服务器

文件系统MCP服务器

安全、高性能 模型上下文协议 （MCP）服务器，为Crush和OpenCode等AI编码代理提供对本地文件系统的安全访问。内置Go，具有目录沙盒、符号链接攻击防御和原子写入功能，因此您可以放心地让AI代理在您控制的范围内读取、写入和管理文件。

特性

• 17个文件系统工具 用于全面的文件操作
• 缺省安全：仅在明确允许的目录中操作
• Symlink攻击防御：解析符号链接并验证目标
• 流媒体支持：大文件的内存高效处理
• 原子写入：使用带重命名的临时文件进行安全的文件操作
• 跨平台：适用于Linux、macOS和Windows
• AI代理优化：行范围支持和动态格式化，实现高效的代码导航

安装

预构建的二进制文件可在 GitHub发布 页面。

Docker（推荐）

运行服务器最简单的方法是使用Docker：

docker pull portertech/filesystem-mcp-server

看 Docker使用 配置示例部分。

去安装

go install github.com/portertech/filesystem-mcp-server/cmd/filesystem@latest

从源代码构建

git clone https://github.com/portertech/filesystem-mcp-server.git
cd filesystem-mcp-server
make build

用法

# Start server with allowed directories
filesystem /path/to/allowed/dir1 /path/to/allowed/dir2

# Enable verbose logging
filesystem -verbose /path/to/dir

# Show version
filesystem -version

# List allowed directories
filesystem -list /path/to/dir

可用工具

read_text_file

使用可选的部分读取和行号读取文本文件的内容。

参数:

• path （必填）：要读取的文件的路径
• head （可选）：从开始读取的行数
• tail （可选）：从末尾开始读取的行数
• start_line （可选）：起始行号（从1开始，含1）
• end_line （可选）：结束行号（从1开始，含1）
• line_numbers （可选）：在输出中包含行号（默认值：false）

备注:

• start_line/end_line 不能与 head/tail
• 使用 start_line/end_line 始终包含行号（针对AI代理使用进行了优化）
• 行号宽度根据总行数动态调整

例子:

// Read specific line range (lines 50-100)
{"path": "/path/to/file.go", "start_line": 50, "end_line": 100}

// Read from line 200 to end of file
{"path": "/path/to/file.go", "start_line": 200}

// Read first 20 lines with line numbers
{"path": "/path/to/file.go", "head": 20, "line_numbers": true}

// Read last 10 lines with line numbers
{"path": "/path/to/file.go", "tail": 10, "line_numbers": true}

退货：文件内容为文本，可选择前缀为行号

read_file

读取文件的完整内容。 弃用：使用 read_text_file 相反。

参数:

• path （必填）：要读取的文件的路径

退货：文件内容为文本

read_multiple_files

同时读取多个文件。单个文件的读取失败不会停止整个操作。

参数:

• paths （必需）：要读取的文件路径数组
• format （可选）：输出格式- text 或 json （默认值：文本）

退货：文件内容及其路径的数组

read_media_file

读取媒体文件并将其内容作为base64编码数据返回。

参数:

• path （必填）：媒体文件的路径

退货：MIME类型的Base64编码文件数据

write_file

使用原子写入（临时文件+重命名）创建或覆盖具有新内容的文件。

参数:

• path （必填）：要写入的文件的路径
• content （必填）：要写入文件的内容

退货：成功确认

edit_file

使用git样式的diff输出对文本文件应用查找/替换编辑。支持精确匹配和空白归一化行匹配。

参数:

• path （必填）：要编辑的文件的路径
• edits （必填）：编辑操作数组，每个操作包含：
  • oldText：要搜索的文本（精确匹配或空格标准化匹配）
  • newText：要替换的文本
  • requireUnique （可选）：只需要一个匹配项（默认值：true）
  • occurrence （可选）：当存在多个事件时，替换哪个事件（1-索引）
• dryRun （可选）：预览更改而不应用（默认值：false）

退货：Git风格差异显示所做的更改

copy_file

将文件复制到新位置。使用流媒体高效处理大文件。

参数:

• source （必需）：源文件的路径
• destination （必需）：目标文件的路径
• overwrite （可选）：覆盖现有目标文件（默认值：false）

退货：成功确认

move_file

移动或重命名文件或目录。

参数:

• source （必填）：当前路径
• destination （必填）：新路径

退货：成功确认

delete_file

删除文件。

参数:

• path （必填）：要删除的文件的路径

退货：成功确认

delete_directory

删除目录。无法删除允许的根目录。

参数:

• path （必填）：要删除的目录的路径
• recursive （可选）：递归删除内容（默认值：false）

退货：成功确认

create_directory

创建一个目录，包括任何必要的父目录。

参数:

• path （必需）：要创建的目录的路径

退货：成功确认

list_directory

列出目录的内容 [FILE] 和 [DIR] 前缀。

参数:

• path （必填）：要列出的目录的路径
• format （可选）：输出格式- text 或 json （默认值：文本）

退货：带有类型指示符的目录条目数组

list_directory_with_sizes

列出目录内容，包括文件大小和可选排序。

参数:

• path （必填）：要列出的目录的路径
• sortBy （可选）：排序字段- name, size，或 modified （默认值：name）
• order （可选）：排序顺序- asc 或 desc （默认值：asc）
• format （可选）：输出格式- text 或 json （默认值：文本）

退货：包含名称、类型、大小和修改时间的条目数组

directory_tree

以JSON格式获取文件和目录的递归树视图。

参数:

• path （必需）：根目录的路径
• excludePatterns （可选）：要排除的glob模式数组

退货：JSON结构 name, type，以及 children 对于每个条目

search_files

递归搜索与glob模式匹配的文件。

参数:

• path （必填）：搜索的起始目录
• pattern （必填）：要匹配的球形图案（例如。， *.go, **/*.json)
• excludePatterns （可选）：要排除的模式数组
• format （可选）：输出格式- text 或 json （默认值：文本）

退货：匹配文件路径数组

get_file_info

获取有关文件或目录的详细元数据。

参数:

• path （必填）：文件或目录的路径

退货：元数据包括：

• size：大小（字节）
• created：创建时间戳
• modified：上次修改时间戳
• accessed：上次访问时间戳
• isDirectory：路径是否为目录
• isFile：路径是否为文件
• permissions：Unix权限字符串

list_allowed_directories

列出服务器有权访问的所有目录。

参数：无

退货：允许的目录路径数组

工具注释

此服务器设置 MCP工具注释 在每个工具上帮助客户了解工具行为：

备注: – 表示未设置提示（被客户端视为未知/未指定）。

配置

克劳德桌面版

增添 ~/Library/Application Support/Claude/claude_desktop_config.json:

使用Docker（推荐）

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/username/Documents:/Users/username/Documents",
        "-v", "/Users/username/Projects:/Users/username/Projects",
        "portertech/filesystem-mcp-server",
        "/Users/username/Documents", "/Users/username/Projects"
      ]
    }
  }
}

使用二进制

{
  "mcpServers": {
    "filesystem": {
      "command": "/path/to/filesystem",
      "args": [
        "/Users/username/Documents",
        "/Users/username/Projects"
      ]
    }
  }
}

Docker使用

在Docker中运行服务器通过容器隔离提供了额外的安全层，将代理的访问权限限制在仅装载的目录上。镜像卷装载中的主机路径（例如。， -v /path:/path 而不是 -v /path:/data)因此，AI代理会看到您在对话中引用的相同路径。

# Run with mounted directories
docker run -i \
  -v /path/to/dir:/path/to/dir \
  portertech/filesystem-mcp-server /path/to/dir

# Multiple directories
docker run -i \
  -v /home/user/projects:/home/user/projects \
  -v /home/user/documents:/home/user/documents \
  portertech/filesystem-mcp-server /home/user/projects /home/user/documents

# Build locally (optional)
docker build -t filesystem-mcp-server .

安全

• 路径验证：所有路径都根据允许的目录进行验证
• Symlink分辨率：Symlinks已解析并验证
• 空字节拒绝：拒绝包含空字节的路径
• 防止父级遍历: .. 序列不能转义允许的目录
• 原子写入：文件写入使用临时文件来防止损坏
• 删除保护：无法删除允许的根目录

Symlink处理

Symlinks在所有工具中都得到了一致的处理，以平衡可用性和安全性。当符号链接解析为允许目录中的路径时，服务器支持符号链接，同时防止基于符号链接的攻击。

按操作类型划分的行为

工具特定行为

安全注意事项

1. TOCTOU预防：写入操作拒绝符号链接，以防止在验证和实际写入之间交换符号链接的竞争情况。

2. 原子写入：文件写入使用临时文件+重命名模式 O_EXCL 用于防止对临时文件进行符号链接攻击的标志。

3. 横向安全：在递归操作期间，跳过符号链接以防止：

   • 循环符号链接的无限循环
   • 通过符号链接将允许的目录转义到父路径
   • 访问允许目录之外的文件

4. 允许的目录解析：允许的目录本身通过以下方式解析 filepath.EvalSymlinks 启动时，符号链接允许目录正常工作。

发展

# Run tests
make test

# Run linter
make lint

# Format code
make fmt

# Build binary
make build

许可证

麻省理工学院