mac-cleaner-mcp

A conservative macOS developer/storage cleaner exposed through the official Model Context Protocol TypeScript SDK. It is not a full disk optimizer: it reports first, refuses broad destructive locations, and supports dry runs.

Tools

• scan_junk: DerivedData, iOS DeviceSupport, Gradle/Android cache, Homebrew cache, Node package cache, Docker reclaimable space, ~/Library/Caches, large Downloads files (>100 MB), and discovered node_modules.

• clean_junk: accepts categories and defaults to dryRun: true. Only DerivedData, DeviceSupport, Android/Gradle, Homebrew, and Docker can be cleaned. Downloads, node_modules, and broad cache roots are intentionally refused.

• get_disk_usage: runs df for a selected path.

Related MCP server: cacheout-mcp

Install and run

Requires macOS, Node.js 20+, and optionally Docker. Do not run as 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 uses stdio, so the process should be launched by the MCP client. Cleaning can delete files; inspect the dry-run output and keep backups before setting dryRun: false.

Claude Desktop / Cursor

Add the absolute path to dist/index.js in the client's MCP configuration:

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

Restart the client, call scan_junk, then call clean_junk with selected categories and dryRun: true. Use false only after reviewing the result. Cursor supports the same stdio MCP server configuration through its MCP settings.

Poke / remote bridge

For a local Poke-compatible bridge, run this server as a child process and proxy MCP JSON-RPC stdin/stdout over an authenticated HTTPS endpoint. A simple option is an SSH/HTTP bridge or ngrok in front of your own bridge process:

ngrok http 8787

Configure the bridge's upstream command as node /ABSOLUTE/PATH/mac-cleaner-mcp/dist/index.js, then register the HTTPS ngrok URL with your Poke/MCP connection. Never expose an unauthenticated endpoint; use an ngrok auth token, allowlist callers, and rotate the URL/token. The cleaner itself is local-only and has no network listener.

Safety

The implementation uses explicit category allowlists, no shell wildcard expansion, dry-run by default, and refuses Downloads, node_modules, and the entire user cache root. Review source and test on a noncritical account before use.