mcp-folder-scout

mcp-folder-scout

询问 Claude 文件夹里有什么、哪些内容已经过时，以及空间都用到哪里去了。

指定电脑上的一个文件夹，即可报告文件名、大小和日期。它无法读取文件内容，也无法移动或删除任何内容。

> What's in my Downloads folder, and what haven't I opened in over a year?

771 files, 43.0 GB. Video is 96% of it.

Not opened in over a year: 102 files, 15.3 GB, almost all of it
video — Barclay lake (27 clips, ~12 GB) and Big (2 clips, 2.5 GB).
If those are backed up elsewhere, they're the obvious candidates.

76 files matched identity, legal, tax, or medical naming and were
excluded from the suggestions above.

安装

claude mcp add --scope user folder-scout -- uvx mcp-folder-scout

对于 Claude Desktop，将以下内容添加到 claude_desktop_config.json 并重启：

{
  "mcpServers": {
    "folder-scout": {
      "command": "uvx",
      "args": ["mcp-folder-scout"]
    }
  }
}

在 macOS 上，配置文件位于 ~/Library/Application Support/Claude/claude_desktop_config.json；在 Windows 上，位于 %APPDATA%\Claude\claude_desktop_config.json。

需要 uv 和 Python 3.10+。兼容任何 MCP 客户端。

工具

工具	功能
scan_folder	汇总文件夹：按类型分类、按使用年限划分，以及列出最大的子文件夹。
list_files	按使用年限、大小、类型或子文件夹筛选单个文件。

两者都只返回元数据。

它不会做什么

它无法删除、移动或重命名任何内容。 代码中没有写入路径。建议会提供给你；由你在 Finder 中自行操作。

它无法读取你的文件。 只有文件名、大小和时间戳会离开你的电脑。

它不会建议删除你的个人文档。 名称包含身份、法律、税务或医疗相关内容的文件和文件夹——例如护照、签证、W2、保险、结婚、房契等——会计入总数并加以标记，但绝不会被列为清理对象。这项保护会向下继承，因此 Passport Renewal/ 里的 scan1.pdf 也会受到保护。

云同步文件夹（iCloud、Dropbox、OneDrive）会被跳过，不会进行处理，因为它们在磁盘上的大小和时间戳没有参考意义。系统文件夹、应用程序包和构建目录也会被跳过。每次扫描都会报告排除的内容。

已知限制

最后访问时间只是参考，并非确凿信息。Spotlight、备份和防病毒软件都可能更新此时间，某些卷则会完全停止跟踪它。当服务检测到访问时间没有得到维护时，会说明这一点并改用修改日期。

“陈旧且未触碰”既适用于垃圾文件，也适用于归档的税务记录。因此才设置了受保护列表，但它无法涵盖所有情况。删除前请仔细检查。

APFS 克隆和硬链接会共享磁盘块。共享同一 inode 的文件只会计数一次，因此总数不会重复计算；但删除克隆文件的一个副本，释放的空间可能少于其标示的大小。

扫描最多处理 50,000 个文件，默认向下遍历三层。结果会缓存五分钟；传入 refresh 可强制重新扫描。

目前还无法检测截图堆积和近似重复的图像。计划加入完全重复项检测。

许可证

MIT

mcp-name: io.github.dharani0804/mcp-folder-scout

mcp-name: io.github.dharani0804/mcp-folder-scout