mac-cleaner-mcp

一个通过官方 Model Context Protocol TypeScript SDK 暴露的保守型 macOS 开发者/存储清理工具。它不是完整的磁盘优化器：它先报告、拒绝危险的广泛删除位置，并支持 dry run（试运行）。

工具

• scan_junk：DerivedData、iOS DeviceSupport、Gradle/Android 缓存、Homebrew 缓存、Node 包缓存、Docker 可回收空间、~/Library/Caches、较大的 Downloads 文件（>100 MB）以及发现的 node_modules。

• clean_junk：接受类别，默认 dryRun: true。只有 DerivedData、DeviceSupport、Android/Gradle、Homebrew 和 Docker 可以被清理。Downloads、node_modules 和广泛的缓存根目录会被有意拒绝。

• get_disk_usage：对所选路径运行 df。

Related MCP server: cacheout-mcp

安装与运行

需要 macOS、Node.js 20+，以及可选的 Docker。不要以 root 身份运行。

git clone https://github.com/FFFames/mac-cleaner-mcp.git
cd mac-cleaner-mcp
npm install
npm run build
node dist/index.js

MCP 使用 stdio，因此该进程应由 MCP 客户端启动。清理可能会删除文件；在将 dryRun 设为 false 之前，请检查 dry-run 输出并保留备份。

Claude Desktop / Cursor

在客户端的 MCP 配置中添加 dist/index.js 的绝对路径：

{"mcpServers":{"mac-cleaner":{"command":"node","args":["/ABSOLUTE/PATH/mac-cleaner-mcp/dist/index.js"]}}}

重启客户端，调用 scan_junk，然后使用所选类别和 dryRun: true 调用 clean_junk。仅在查看结果后才使用 false。Cursor 通过其 MCP 设置支持相同的 stdio MCP 服务器配置。

Poke / 远程桥接

对于本地 Poke 兼容桥接，请将此服务器作为子进程运行，并通过经过身份验证的 HTTPS 端点代理 MCP JSON-RPC stdin/stdout。一个简单的选择是在你自己的桥接进程前使用 SSH/HTTP 桥接或 ngrok：

ngrok http 8787

将桥接的上游命令配置为 node /ABSOLUTE/PATH/mac-cleaner-mcp/dist/index.js，然后使用你的 Poke/MCP 连接注册 HTTPS ngrok URL。切勿暴露未经身份验证的端点；请使用 ngrok auth token、允许调用者列表，并轮换 URL/token。清理器本身仅限本地运行，没有网络监听器。

安全性

该实现使用明确的类别允许列表、无 shell 通配符展开、默认 dry-run，并拒绝 Downloads、node_modules 和整个用户缓存根目录。使用前请审查源代码并在非关键账户上测试。