DiskSweep MCP
Provides local disk analysis and cleanup for macOS, including APFS-aware usage scanning, folder investigation, cleanup-candidate and app-leftover detection, proposal creation, moving approved items to Trash, and cleanup history.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
DiskSweep MCP
Find what is filling your Mac. Understand it. Review what goes.
A local Model Context Protocol (MCP) server for disk analysis and cleanup. Connect it to your assistant to inspect disk usage, investigate unfamiliar folders, and prepare a cleanup proposal.
Quick start · Usage · Tools · Safety · Contributing
Why DiskSweep?
Disk usage tools show where space goes. DiskSweep gives your assistant the measurements and context to help explain what those folders are, what can be recreated, and what needs your review.
Measure actual disk usage. A native macOS scanner accounts for exact APFS clones and hard links. Later scans use the macOS change journal to refresh changed folders when possible.
Find common cleanup candidates. Rules cover app caches, logs, package managers, development tools, and AI tools. Other detectors find stale build folders, old downloads, unused apps, and app leftovers.
Investigate the unfamiliar. Large folders without a matching rule appear separately. Inspect their file types, ages, likely owner app, and signs of databases or media before making a recommendation.
Keep context between chats. Save findings, remember what to keep, review cleanup history, and see when a folder grows back.
Review a concrete proposal. Cleanup operates on numbered proposal items. The server checks paths again before moving them to the Trash.
Related MCP server: mac-disk-cleaner
Quick start
Requirements
macOS 11 or later, on Apple Silicon or Intel. Windows and Linux are not supported yet.
Node.js 20 or later to run the server. For building and testing, use Node.js 22.12 or later.
An MCP client that can launch a local server over stdio, the standard input/output connection used by this package.
Run with npm
npx -y disksweep-mcp --versionNo global installation is needed. Your MCP client starts the server through npx when it connects.
Connect your assistant
Add this server to your client's MCP configuration. The client will download and run the npm package.
{
"mcpServers": {
"disksweep": {
"command": "npx",
"args": ["-y", "disksweep-mcp"]
}
}
}claude mcp add disksweep -- npx -y disksweep-mcpSee the Claude Code MCP documentation for scope and connection settings.
Add this entry to ~/.codex/config.toml:
[mcp_servers.disksweep]
command = "npx"
args = ["-y", "disksweep-mcp"]See the Codex MCP documentation for connection and tool approval settings.
Use the JSON configuration above in the client's MCP settings. Claude Desktop uses claude_desktop_config.json; Cursor uses .cursor/mcp.json in a project or ~/.cursor/mcp.json globally. Other clients may use a different configuration structure. The server command is npx, with -y and disksweep-mcp as its arguments.
If a desktop client cannot find npx, run command -v npx in your terminal and use the returned absolute path as command.
For more complete scan results, give the app running the server Full Disk Access in System Settings → Privacy & Security. Without it, protected folders can be unreadable and reported sizes are lower bounds. Restart the host app after changing permissions.
Usage
Start with a request like:
Do a disk checkup. Explain the largest cleanup candidates and show me a proposal before moving anything.
Or ask a more focused question:
What is this large folder in Application Support? Inspect it and explain what might be lost if I remove it.
I uninstalled Cursor. Find its leftover files and explain why each one matches.
Keep my Downloads/Research folder and do not suggest it again.
The bundled disk_checkup MCP prompt guides the assistant through this workflow:
Scan → Analyse → Inspect → Propose → User selects items → Move to TrashA proposal includes item numbers, sizes, paths, reasons, and a cleanup tier. You can approve specific numbers and leave the rest. The client must wait for your approval before calling the cleanup tool. See Safety for the boundary between client approval and server checks.
Moving files to the Trash does not free their space yet. They remain there until the Trash is emptied. Use Finder to restore items before permanent deletion.
Read-only report
npx -y disksweep-mcp reportThis scans, updates the local index, and prints an analysis without deleting user files. You can run it from your own cron or launchd routine. DiskSweep does not schedule itself.
What it adds to an AI chat
The assistant supplies the reasoning. DiskSweep supplies local measurements, disk-specific rules, persistent context, and a constrained cleanup interface.
Task | Plain chat, without local tools | Assistant with DiskSweep |
Find what uses space | Explains commands or asks you to share output | Measures your Mac and returns focused summaries |
Understand an unfamiliar folder | Reasons from what you describe | Inspects names, sizes, ages, file types, and likely app ownership |
Find common cleanup candidates | Suggests general places to look | Applies rule packs and detectors to local evidence |
Continue next time | Needs the relevant context again | Loads its saved index, notes, keep decisions, and cleanup history |
Act on findings | Gives you instructions | Moves selected proposal items to the Trash after server checks |
An assistant with shell access can already do much of this. DiskSweep packages the work into reusable tools, adds APFS-aware sizing and incremental scans, and applies path checks in code. It does not make the model inherently smarter, and it cannot prove that every unfamiliar file is disposable.
Tools
Area | Tool | Purpose |
Overview |
| Free space, disk pressure, macOS volumes, scan age, and recorded growth |
Scanning |
| Build or refresh the index and check progress |
Investigation |
| Drill into folder sizes and inspect metadata, likely ownership, and saved context |
Analysis |
| Find candidates by tier, growing folders, and large unexplained folders |
App leftovers |
| Find data associated with an uninstalled app and explain each match |
Memory |
| Save findings and keep decisions, list them, or forget an entry |
Proposal |
| Freeze a numbered list from detector results or investigated paths |
Cleanup |
| Re-check and move selected proposal items to the Trash |
Trash |
| List old Trash items, then permanently delete the token-bound set |
History |
| Review recorded cleanup actions and item sizes |
Cleanup tiers
Tier | Meaning | Typical example |
| Expected to regenerate automatically | Recognised app caches or logs |
| Can be recreated with a command or download | Dependencies in a stale project |
| May contain personal data or work | Old downloads, large files, or an unfamiliar folder |
Tiers help prioritise review. They are not guarantees, and every tier uses the proposal workflow. Paths proposed by the assistant without a detector match always use review.
Rule packs: JSON rules in
rules/cover apps, system caches, development tools, and AI tools.Stale projects: finds regenerable folders such as
node_modules,.venv,target, and.nextin projects inactive for 30 days by default.Files: finds large files and Downloads/Desktop items unused for 60 days by default.
Unused apps: checks apps not opened for 90 days by default.
App leftovers: searches common app data locations using bundle IDs and whole-word names.
rules/app-identities.jsonmaps known apps to their IDs. Inferred matches carry lower confidence. Installed apps and recently active data are excluded from leftover suggestions; protected items can be reported without being removable.Duplicates: optional content hashing identifies matching files. Native sizing accounts for shared APFS blocks when estimating wasted space. Duplicate detection is excluded from the default analysis; request it through the
detectorsargument toanalyse.
Safety
DiskSweep separates the client's approval workflow from checks enforced by the server.
The server instructions tell the assistant to show a proposal and wait for approval of specific item numbers. The server accepts a proposal ID and item numbers, but it cannot independently verify that a human approved them. Keep your MCP client's confirmation controls enabled for destructive tools.
Within DiskSweep, the cleanup path applies these checks:
Restricted locations. Cleanup is limited to allowed paths inside your home folder and third-party app bundles directly in
/Applications. The guard blocks operating-system paths, credential stores, synced data, Git internals, and other protected locations.Checks before moving. Paths must use their exact on-disk spelling. The guard checks parent paths, ownership, protected file flags, mount points, and app restrictions. Proposal items also record file identity; items in the
reviewtier are skipped if their contents changed since the proposal.Trash first. Normal cleanup moves items to the Trash. Proposals expire after 24 hours. DiskSweep does not use
sudo.Separate permanent deletion.
empty_old_trashrequires a list token andconfirm: true. Tokens expire after 15 minutes and can be used once. The deletion code limits itself to the recorded set and skips replaced items. Lists longer than 30 items are abbreviated in the current tool output; use Finder if you need to inspect every item before deletion.
These checks govern DiskSweep tools. They do not restrict an assistant's separate shell tools or protect against a process that can change the server or its local state. Review the proposed paths and reasons before cleanup.
The guard protects system locations such as /System, /usr, /bin, /private, and /Library. Home-folder protections include credentials, preferences, Mail, Messages, Safari data, cloud sync folders, Apple app data, and the internals of media libraries. Standard folders such as ~/Documents and ~/Library/Caches cannot themselves be removed.
Some rules have narrow exceptions, such as individual Mail Downloads attachments. A whole media library can be proposed for review even though its internals are protected. See src/safety/guard.ts for the exact rules.
Proposal execution is in src/proposal.ts. Permanent Trash deletion has its own checks in src/trash.ts.
Configuration and privacy
Add optional settings to ~/.disksweep/config.json:
{
"protected": ["~/Documents/Thesis"],
"staleProjectDays": 30,
"staleDownloadDays": 60,
"unusedAppDays": 90
}The index, daily snapshots, proposals, notes, and cleanup history live in ~/.disksweep/. Keep decisions and additional protected paths exclude items from new proposals.
Scanning and folder inspection use metadata. Optional duplicate detection reads file contents locally to calculate hashes. App detection also reads app metadata. Tool results can contain file names, paths, sizes, dates, download URLs, and saved notes; your MCP client may send those results to its model provider. DiskSweep itself does not need a model API key.
How sizing works
The native dsize helper uses macOS getattrlistbulk to read directory metadata in batches. It counts allocated bytes, deduplicates exact APFS clones and hard links within a scan, and skips cloud-only files without downloading them. It stays on one volume and does not follow symlinks.
Partly modified clones are counted in full, so shared blocks can still be overcounted. The index retains folders above a configurable threshold, 10 MB by default, and up to 200 large files. Incremental scans use FSEvents, the macOS file-change journal, with a full-scan fallback when needed. If the native helper is unavailable, sizing falls back to /usr/bin/du with reduced capabilities.
Scan time depends on your disk, file count, permissions, and changed folders. Reported sizes are estimates of disk usage, not a promise of space reclaimed after deletion.
Contributing
Build from source
Use Node.js 22.12 or later and Apple Command Line Tools with clang:
git clone https://github.com/gautamjajoo/disksweep-mcp.git
cd disksweep-mcp
npm ci
npm run build
npm testThe build compiles TypeScript and a universal native scanner for Apple Silicon and Intel. To use your local build, set your MCP server command to node and its argument to the absolute path of dist/index.js in your checkout.
The test suite covers path guards, proposal execution, app leftovers, locking, clone-aware sizing, and incremental scans. Run npm run build after code changes and before testing changes to the native helper.
Contributions to rule packs and app identities are welcome. Include the paths you want to match, what they contain, how the data is recreated, and any cases where removing it could lose user data. Report bugs through GitHub Issues.
Inspired by the disk exploration workflow of OmniDiskSweeper and OpenSweeper. DiskSweep does not use their code.
License
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
- DNS-DATA RemoteDeprecatedcom.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
Your own computer's files from ChatGPT or Claude: folder rules, confirmations and undo.
User-owned files and explicit AI Memories for authorized assistants with scoped access.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables local AI assistants to inspect Windows disk usage with treemap and folder X-ray views, retrieve cleanup previews, and receive application removal guidance, while exposing only non-destructive commands through MCP.MIT
- 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
- AlicenseAqualityCmaintenanceEnables an AI assistant to perform read-only scans of Windows drives and identify cleanup candidates, including caches, temporary files, and largest files.11MIT
- AlicenseAqualityCmaintenanceEnables AI assistants to scan a Mac for reclaimable disk space and safely move selected items to the Trash, with dry-run defaults, protected paths, and confirmation before permanent deletion.12MIT