# 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.

## Install and run

Requires macOS, Node.js 20+, and optionally Docker. Do not run as root.

```bash
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:

```json
{"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:

```bash
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.