MacSweep
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| PYTHONPATH | No | Path to the cloned macsweep repo, used when launching the server directly with `python3 -m macsweep.mcp_server` instead of via uvx. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| get_disk_usageB | Total, used and free space on the startup disk. |
| list_categoriesA | What MacSweep can scan. Each category has a risk level: 'safe' (rebuilt automatically) or 'review' (user data, check each item with the user). |
| start_scanA | 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). |
| get_scan_statusA | 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. |
| cancel_scanA | Stop the running scan. Results found so far stay available. |
| list_itemsB | 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. |
| move_to_trashA | 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. |
| empty_trashA | 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. |
| protect_pathA | Never offer or remove this file or folder (and anything inside it) again. Use when the user says to keep something. |
| unprotect_pathA | Remove a path from the protected list. It shows up again in the next scan. |
| list_protectedA | Paths the user chose to keep. MacSweep never offers or removes them. |
| reveal_in_finderA | Open a Finder window with this item selected, so the user can look at it. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
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.