MacSweep
Provides tools for scanning and cleaning macOS disk space, including disk usage, cache/log/download categories, listing items, moving items to the Trash, emptying the Trash, protecting paths, and revealing items in Finder.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MacSweep Scan my Mac for reclaimable space and show me what you'd remove first"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MacSweep
Free up space on your Mac with a clean local app, or let any AI assistant do it for you through MCP.

You decide what goes. Every item has a checkbox. Safe categories are preselected; anything that holds your own data starts unselected.
Nothing is deleted behind your back. Items move to the Trash, so you can restore them until you empty it.
Keep things forever. Click the lock on any item and MacSweep never offers it again, in the app or through MCP.
Works with AI assistants. The built-in MCP server lets Claude, Cursor, ChatGPT or any MCP client scan and clean, with the same safety rules.
Local and dependency-free. Pure Python standard library. No network calls, no telemetry, no account.
What it checks
Category | Risk | What it is |
App caches | Safe |
|
Logs | Safe |
|
Developer caches | Safe | Xcode DerivedData and DeviceSupport, simulator caches, npm, pnpm, Gradle, Cargo. |
Installers | Safe |
|
| Review first | Tool and model downloads (Hugging Face, pip, Playwright…). |
| Review first | Dependencies in your projects. |
Old downloads | Review first | Items in Downloads not modified for 90 days. |
iPhone and iPad backups | Review first | Local device backups made by Finder. |
Large files | Review first | Files over 500 MB in your home folder, outside Library. |
MacSweep only looks inside your home folder. It never touches system files, and it never looks inside app bundles, Photos or Music libraries, or Git folders.
Related MCP server: dev-disk-doctor
Use the app
Requires macOS and Python 3.9 or later (already on most Macs).
With uv:
uvx --from git+https://github.com/NKSTUD/macsweep macsweepOr without installing anything: clone the repo and double-click MacSweep.command.
git clone https://github.com/NKSTUD/macsweep.git
open macsweep/MacSweep.commandThe app opens in your browser on a private local address. The scan shows its progress step by step, and you can stop it at any time and keep what was found so far.

Use it from an AI assistant (MCP)
MacSweep includes an MCP server, so any compatible AI assistant can scan your Mac and clean it with your approval.
Claude Code
claude mcp add macsweep -- uvx --from git+https://github.com/NKSTUD/macsweep macsweep-mcpClaude Desktop, Cursor, Windsurf, and other clients. Add this to the client's MCP config file (claude_desktop_config.json, .cursor/mcp.json, …):
{
"mcpServers": {
"macsweep": {
"command": "uvx",
"args": ["--from", "git+https://github.com/NKSTUD/macsweep", "macsweep-mcp"]
}
}
}No uv? Clone the repo and point the client at Python directly:
{
"mcpServers": {
"macsweep": {
"command": "python3",
"args": ["-m", "macsweep.mcp_server"],
"env": { "PYTHONPATH": "/path/to/macsweep" }
}
}
}Then ask something like "Free up some space on my Mac. Show me what you'd remove before doing anything."
Tools
Tool | What it does |
| Total, used and free space. |
| The categories above, with their risk level. |
| Starts a scan in the background, for all categories or only some. |
| Progress, current step and size found per category. Can wait up to 50 s for the scan to finish. |
| Stops the scan and keeps partial results. |
| Items found in a category, with path, size and date. Paginated and sortable. |
| Moves items to the Trash. Dry run by default. |
| Empties the Trash. Requires |
| Manage items that must never be removed. |
| Shows an item in Finder so you can look at it. |
Safety rules for AI assistants
These rules are enforced by the server, not left to the model:
Only paths found by the latest scan can be moved. Any other path is refused, even if the model asks for it.
Paths outside your home folder are refused.
Protected paths, and everything inside them, are refused.
move_to_trashis a dry run unless the model explicitly passesdry_run: false, and it only ever moves items to the Trash.empty_trashis the only permanent action, and it requiresconfirm: true.The server tells the model to show you the list and get your approval before moving anything, and to treat "Review first" categories as your personal data.
Permissions
macOS protects some folders, such as Mail data and some app containers. MacSweep skips what it can't read. To scan everything, give Full Disk Access to the app that runs MacSweep (Terminal, or your AI client) in System Settings > Privacy & Security > Full Disk Access.
The first time you empty the Trash, macOS asks whether the app may control Finder. MacSweep needs this to empty the Trash the same way Finder does.
Your protected list is stored in ~/.config/macsweep/protected.json.
Development
python3 -m unittest discover testsThe tests run against a throwaway home folder, so they never touch your files. The project layout:
macsweep/core.py— scanning and cleaning engine, with the safety checksmacsweep/app.pyandmacsweep/ui.html— the local appmacsweep/mcp_server.py— the MCP server (JSON-RPC over stdio)
Contributions are welcome. Please open an issue first for larger changes.
License
MIT
Available Tools
12 toolscancel_scanA
Stop the running scan. Results found so far stay available.
Inputs: no named parameters.
empty_trashADestructive
Permanently delete everything in the Trash, including items the user put there themselves. Irreversible. Only call after the user explicitly asks to empty the Trash. Requires confirm: true. macOS may ask the user once to let the app control Finder.
Inputs: confirm (required).
get_disk_usageBRead-only
Total, used and free space on the startup disk.
Inputs: no named parameters.
get_scan_statusARead-only
Progress of the current scan and a size summary per category. Set wait_seconds to block until the scan finishes or the time runs out.
Inputs: wait_seconds.
list_categoriesARead-only
What MacSweep can scan. Each category has a risk level: 'safe' (rebuilt automatically) or 'review' (user data, check each item with the user).
Inputs: no named parameters.
list_itemsBRead-only
Items found in one category by the latest scan, with full path, size and last modified date. Only these exact paths can be passed to move_to_trash.
Inputs: category (required), sort, limit, offset.
list_protectedARead-only
Paths the user chose to keep. MacSweep never offers or removes them.
Inputs: no named parameters.
move_to_trashADestructive
Move items found by the latest scan to the Trash (restorable until the Trash is emptied). Always show the user the list and total size and get their explicit approval first. dry_run defaults to true and only reports what would happen; set dry_run to false to act. Paths not found by the latest scan, outside the home folder, or protected are refused.
Inputs: paths (required), dry_run.
protect_pathAIdempotent
Never offer or remove this file or folder (and anything inside it) again. Use when the user says to keep something.
Inputs: path (required).
reveal_in_finderARead-only
Open a Finder window with this item selected, so the user can look at it.
Inputs: path (required).
start_scanARead-only
Start scanning in the background. Returns immediately; follow up with get_scan_status. A full scan takes 1 to 5 minutes, mostly 'large_files' and 'dot_cache'. Pass categories to scan only some of them (much faster).
Inputs: categories.
unprotect_pathAIdempotent
Remove a path from the protected list. It shows up again in the next scan.
Inputs: path (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Each tool targets a distinct resource and action: scan lifecycle (start/get_status/cancel), discovery (list_categories vs list_items vs list_protected), and destructive ops (move_to_trash vs empty_trash) are clearly separated. The descriptions reinforce the boundaries, e.g. list_items vs list_categories vs list_protected are unambiguous.
All 12 tools use consistent snake_case verb_noun naming (list_categories, start_scan, get_scan_status, move_to_trash, protect_path, reveal_in_finder). Verb choice is predictable (list_*, get_*, *_path, *_trash), so an agent can infer new tool names.
12 tools is well within the ideal 3-15 range for a disk-cleanup server. Every tool earns its place: scan control, discovery, trash operations, protection management, and helpers like get_disk_usage and reveal_in_finder.
The surface covers the full scan-clean-protect lifecycle plus disk usage and Finder reveal, with no dead ends for the core workflow. The only minor gap is the inability to restore items from the Trash via a tool (users must use Finder), and no scheduling, but these are workable.
Maintenance
Related MCP Connectors
- DNS-DATA RemoteDeprecatedcom.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
Your own computer's files from ChatGPT or Claude: folder rules, confirmations and undo.
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
User-owned files and explicit AI Memories for authorized assistants with scoped access.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables natural-language management of macOS disk cleanup by scanning large files, AI model weights, and caches, identifying duplicates, and safely moving files to Trash or permanently deleting them with confirmation.MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to scan a developer machine for disk space hogs, audit git worktrees for stale or orphaned ones, re-check individual findings, and run allowlisted cleanup actions as dry runs unless explicitly confirmed. Risky items are reported with warnings and refused by default.1,042 npm2MIT
- AlicenseNot gradedqualityCmaintenanceEnables an AI assistant to measure macOS disk usage, investigate unfamiliar files and folders, identify cleanup candidates, and prepare numbered cleanup proposals that move approved items to the Trash only after server-side path checks.16 npm1MIT
- AlicenseAqualityCmaintenanceEnables an AI assistant to perform read-only scans of Windows drives and identify cleanup candidates, including caches, temporary files, and largest files.11MIT