Skip to main content
Glama
MacSweep
by NKSTUD

MacSweep

Free up space on your Mac with a clean local app, or let any AI assistant do it for you through MCP.

MacSweep results view

  • 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

~/Library/Caches. Apps rebuild these on their own.

Logs

Safe

~/Library/Logs. Diagnostic history.

Developer caches

Safe

Xcode DerivedData and DeviceSupport, simulator caches, npm, pnpm, Gradle, Cargo.

Installers

Safe

.dmg and .pkg files in Downloads.

~/.cache folder

Review first

Tool and model downloads (Hugging Face, pip, Playwright…).

node_modules folders

Review first

Dependencies in your projects. npm install brings them back.

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 macsweep

Or without installing anything: clone the repo and double-click MacSweep.command.

git clone https://github.com/NKSTUD/macsweep.git
open macsweep/MacSweep.command

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

Scan in progress

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-mcp

Claude 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

get_disk_usage

Total, used and free space.

list_categories

The categories above, with their risk level.

start_scan

Starts a scan in the background, for all categories or only some.

get_scan_status

Progress, current step and size found per category. Can wait up to 50 s for the scan to finish.

cancel_scan

Stops the scan and keeps partial results.

list_items

Items found in a category, with path, size and date. Paginated and sortable.

move_to_trash

Moves items to the Trash. Dry run by default.

empty_trash

Empties the Trash. Requires confirm: true.

protect_path / unprotect_path / list_protected

Manage items that must never be removed.

reveal_in_finder

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_trash is a dry run unless the model explicitly passes dry_run: false, and it only ever moves items to the Trash.

  • empty_trash is the only permanent action, and it requires confirm: 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 tests

The 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 checks

  • macsweep/app.py and macsweep/ui.html — the local app

  • macsweep/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 tools
cancel_scanA

Stop the running scan. Results found so far stay available.

Inputs: no named parameters.

empty_trashA
Destructive

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_usageB
Read-only

Total, used and free space on the startup disk.

Inputs: no named parameters.

get_scan_statusA
Read-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_categoriesA
Read-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_itemsB
Read-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_protectedA
Read-only

Paths the user chose to keep. MacSweep never offers or removes them.

Inputs: no named parameters.

move_to_trashA
Destructive

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_pathA
Idempotent

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_finderA
Read-only

Open a Finder window with this item selected, so the user can look at it.

Inputs: path (required).

start_scanA
Read-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_pathA
Idempotent

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

    A4/5.0

    Scored across 12 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      2
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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 npm
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables an AI assistant to perform read-only scans of Windows drives and identify cleanup candidates, including caches, temporary files, and largest files.
      1
      1
      MIT