file-manager-mcp

给 AI 助手用的沙箱文件管理器 —— 目录列表、读、写、搜索,全部锁在指定根目录内。

为什么做这个

让 AI 碰文件系统,几乎所有事故都来自同一个根因:路径校验做在字符串上,而不是解析后的真实路径上。

用户给: ../../../../etc/passwd          → 字符串前缀检查能过
用户给: data/link → /etc (符号链接)     → 字符串前缀检查也能过

这个服务在每次操作前先把路径 resolve()(展开符号链接、消掉 ..),再做根目录前缀比对。两个逃逸向量一起堵死。

一个真实的教训(search 的软链绕过):read/write 都做了 resolve 校验, 但最初的 search 用 os.walk + read_bytes 直接读 —— 根目录内的文件软链 指向外部时,外部文件内容被原样读出。修复:每个候选文件都先 resolve 再校验,越界跳过并在结果里报告 escape_skipped(见 git 的 fix(security) 提交和对应的回归测试)。

Related MCP server: File Manager MCP Server

安全边界

硬链接那条是对抗性验证补充的:根目录内预置的硬链接(需本地文件系统权限, 典型场景是"根目录为共享/可写目录")能穿透 read/search/write 三条路径, resolve() 对此无能为力。修复用 O(1) 的 nlink 检测;代价是根内合法的 硬链接文件默认被拒,需要时用 MCP_ALLOW_HARDLINKS=1 放行。

安装

pip install -e .

配置

{
  "mcpServers": {
    "files": {
      "command": "file-manager-mcp",
      "env": {
        "MCP_FILE_ROOT": "/home/me/projects",
        "MCP_WRITE_ENABLED": "1"
      }
    }
  }
}

多个根目录用 : 分隔(Linux/macOS)或 ;(Windows)。

工具

list_dir(path=".", pattern="*")

列目录,glob 过滤。返回名称(目录带 /)、类型、大小、修改时间。

read_file(path, offset=1, limit=0)

文本读取,带行号。自动识别二进制(前 8KB 含 NUL 即判定),超 1 MB 直接拒绝而不是截断后假装成功。

write_file(path, content, append=false)

写入。父目录不存在会自动创建。append=true 追加。

search(path=".", name_glob="*", content_regex="", max_results=50)

双条件搜索:文件名 glob + 内容正则。同时给出时取交集。内容命中带行号和片段。

会拒绝什么

[拒绝] 路径越界。允许的根目录: /home/me/projects          # ../../etc/passwd
[拒绝] 路径越界。允许的根目录: /home/me/projects          # 指向外部的符号链接
[拒绝] 文件 5242880 字节,超过 1048576 字节上限(避免灌爆上下文)
[拒绝] 写操作已被禁用(MCP_WRITE_ENABLED=0)
[二进制] app.bin 含 NUL 字节,判定为二进制文件(2048 字节)不返回内容

测试

pip install -e ".[dev]"
pytest tests/ -v

License

MIT