DiskWise MCP server
Commit Oct 31, 2026Lets an AI client scan macOS disk usage and move safe cache files like node_modules, Xcode DerivedData, and Docker files to the Trash.
Also known as DreamOfXM/diskwise
- Stars
- 33
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 31, 2026
- License
- Apache-2.0
What is DiskWise MCP?
DiskWise lets an AI client scan macOS disk usage and move safe cache files like node_modules, Xcode DerivedData, and Docker files to the Trash.
Summary generated from the project's README
About DiskWise MCP server
Developers looking to reclaim storage on macOS can use DiskWise to identify and manage large, non-essential files. The tool specifically targets developer-centric space hogs like node_modules, Xcode DerivedData, Docker.raw, and Homebrew caches. Unlike traditional cleaners that use permanent deletion, this server moves identified files to the Trash, allowing for a full undo of any cleanup operation before the Trash is emptied.
This MCP server functions as a local tool that integrates with AI clients such as Claude Code, Cursor, Zed, and Claude Desktop. To use it, you must install the direct-download build in your Applications folder and register the binary with the mcp argument. It provides a safe environment by refusing to touch risky system areas or folders that do not match known cache structures. It also tracks disk growth by comparing current scans against previous snapshots to highlight sudden bursts of file accumulation.
What you can do with it
- 1Analyze disk usage patternsAsk your AI agent to scan your Mac to see which folders are consuming the most space.
- 2Identify rapid file growthUse the tool to detect if a specific application is suddenly generating massive amounts of data.
- 3Revert accidental cleanupsTell the agent to undo a recent deletion if you realize you needed those files.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachabledreamofxm/diskwise is public and reachablegithub.com/dreamofxm/diskwise ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-31github.com/dreamofxm/diskwise ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubDiskWise
See where your Mac's disk actually went — and undo every cleanup with one tap.
Xcode DerivedData · node_modules · Docker.raw · Homebrew cache · crash dumps
Nothing is ever deleted for real. Every removal goes to the Trash and stays undoable until you empty it. 8 MB · native SwiftUI · 10 UI languages · no telemetry · Apache-2.0
Scan → open a row → two taps → undo. Shot against a synthetic home folder, so the numbers on screen are invented — the orange strip says so.
brew tap DreamOfXM/diskwise https://github.com/DreamOfXM/diskwise
brew install --cask dreamofxm/diskwise/diskwise
Mac App Store · DMG + SHA-256 · 22-second demo
If it won back space you'd written off, a ⭐ is how the next person finds it.
| Reads what actually grows | DerivedData, node_modules, Docker.raw, Homebrew cache, Crashpad dumps — measured, grouped, and attributed to what wrote them. |
| Growth, not just size | Every scan is diffed against the previous one. A burst gets a red badge (+2,674 files in under a minute), slow creep gets amber, a folder you cleared reads as a decrease. |
| Undo instead of a warning dialog | Removals land in the Trash. Batch undo works until you empty it. There is no "smart clean" button that runs on its own. |
| It declines | A folder that looks like a cache but isn't structured like one is never flagged — it goes to a read-only list with the reason it isn't offered. |
A free, open-source CleanMyMac alternative for the folders a developer actually fills up.
docs/safe-to-delete.md covers 80 of the usual space hogs on macOS: what each one is, what deleting it does, and what it costs if you were wrong. It is generated from the same data the app reads at scan time (the tables are in Chinese; Sources/DiskCleaner/Resources/safety_db.json is the machine-readable original).
v2.3 came out of one incident: 2,674 crash dumps landed in Chrome's Crashpad folder in 57 seconds. Every tool on that machine said "Chrome", and none of them were lying — the folder was Chrome's and so was the executable path inside each dump. What put Chrome into a crash loop was something else entirely, and the only place that said so was the environment captured inside the dumps themselves. This release is built so that the same event reads itself off the screen instead of leaving you to guess.
- Crash dumps get named, not just counted. Crashpad folders are recognized by their structure wherever an engine writes them, and attributed to the app that hosts the path. A look-alike folder without that structure is never flagged; it goes to a read-only list instead.
- How fast something is growing, without a daemon. Every scan leaves a snapshot, so each entry is compared with the previous one. A burst gets a red badge — the incident above reads back as +2,674 files in under a minute — slow accumulation gets amber, and a folder you cleared shows up as a decrease rather than an alarm.
- What was actually driving it (off by default). Turn on Content probe under Diagnostics in Settings (⌘,) and DiskWise reads the headers of a few sample dumps: the executable path, the bundle identifier, and any agent session fingerprints. In the incident above, that is the only place the real name appears. Fingerprints always display redacted and nothing leaves the machine.
- Trim by retention. The first time the category appears you're offered "keep the newest 2,000" — adopt it or dismiss it, one click either way, and nothing ever runs by itself. The preview is the result, whole batches undo, and the folder skeleton stays in place.
- A home for what we only observe. Everything the scan can see but this tool will never delete — system areas, admin-only report folders, look-alikes — now has a read-only page, each row carrying the reason it isn't offered.
v2.2 taught the scan to recognize the model caches that live inside your own projects, and to identify an engine's self-managed cache by its layout on disk rather than by name.
Contents
- Quick start
- For AI agents
- Why this exists
- What you get
- Screenshots
- Install
- Build from source
- FAQ
- Known limits
- Roadmap
- Feedback
- Privacy
- License
Quick start
The GIF at the top of this page plays this exact order:
- Open Overview — it walks the whole volume and draws the result as one ring, with the ledger beside it.
- Click any row in that ledger — the folders under it unfold right there, and the ring steps back to a small reference dial.
- Click the arc you can move twice: the first click arms it, the second moves it to the Trash. Undo puts it back, and emptying the Trash stays Finder's call.
For AI agents
The direct-download build ships a diskwise CLI (the App Store build doesn't), and it doubles as a
Model Context Protocol server — Claude Code, Cursor, Codex, Qoder,
OpenCode, Zed, ZCode and Claude Desktop can all reclaim disk space for you. It can't rm -rf: the only
removal path moves known-safe items to the Trash, every operation is undoable, and risky locations are
never touchable.
Put DiskWise in /Applications before copying this. The path below points at that copy; a build
left on the Desktop or run straight off the mounted DMG stops working the moment it moves or gets deleted.
Claude Code takes one line in Terminal:
claude mcp add diskwise -- "/Applications/DiskWise.app/Contents/MacOS/diskwise" mcp
Or click to install, no Terminal needed — the app registers itself as the server:
Install in Cursor · Install in VS Code
These point at /Applications/DiskWise.app, so they only work once the direct-download build
is in that folder. The App Store build has no CLI, so it has nothing to register.
Then just ask your agent "see what's worth cleaning on my Mac" — it scans, drafts a plan,
shows you the summary, and only moves anything after you agree. The eight above are the ones we
verified line by line; any client that can host a local stdio MCP server takes the same two values —
this binary's path, and the mcp argument. If one of them can't connect, that's on the client:
issues and PRs welcome. Details, snippets for the other seven
clients and the full safety model: docs/AGENTS-CLI.md.
Why this exists
A disk cleaner has to read a lot of your machine before it can tell you anything useful. Most of
them are closed-source, ship a background daemon, and treat rm -rf as a feature.
We go the other way:
| DiskWise | |
|---|---|
| Delete path | One — FileManager.trashItem. Everything lands in the Trash. |
| Undo | Yes, per operation, for the whole session. |
| Protected paths | Home itself, ~/Library, and friends can never be removed wholesale. |
| Emptying the Trash | Finder does it, never this app. Direct build: the app asks Finder and you confirm once more. App Store build: the sandbox kills that event — measured behaviour, no permission prompt even appears — so the same button opens the Trash and you press ⌘⇧⌫. |
| Docker images | Read-only. Virtual disks have no per-image path, so the app points instead of pretending. |
| Network | None. No updater, no analytics, no ads. |
| Price | Nothing. Every feature and all six skins ship unlocked in this build. |
| Runtime | A single .app. No Python, no port, no daemon. |
The cache list explains each entry it can — what it is, what happens if you delete it, how it comes back. We only write that text for entries we actually understand, so some rows carry it and some don't. WeChat, DingTalk and WeCom are covered, because on many machines those three alone hold tens of gigabytes.
It is built for machines that have been used by a developer for a few years — the ones where
node_modules, Docker volumes, Xcode DerivedData, and ten GB of caches quietly took over.
What you get
See the space
- Overview — the volume drawn as one ring: a slice is a block of bytes this pass actually
measured, and the slices add up to the whole disk (top folders + everything else counted + not
measured + purgeable + free).
- The light band sits exactly on the edge of what's been measured so far.
- A slice you can move away whole takes two taps: the first arms it, the second sends it to the Trash, and it lets go on its own after 3 seconds.
- The button under the ring opens a list, not a delete: one row per spot it can take, each saying what removing it costs, with the harmless ones pre-ticked and the re-downloadable ones left for you to tick. The next screen repeats that list as a confirmation, and only its button moves anything — the result screen after it puts the whole batch back.
- There is one list, the ledger beside the ring. Open a row and its detail unfolds right there — the folders under it, the places behind Other counted, the volumes behind Not measured.
- While a row is open the ring steps back to a small reference dial, and Reveal and Dig in sit on that row.
- Whole-disk sweep — no scope to guess at. The open-source build walks the whole volume
(whitelisted system roots included, other users' homes included); the sandboxed Mac App Store
build walks everything its grant can reach and says so on screen.
- Either way it covers the volume, not just the tidy corners of your home folder.
- A coverage line that names what it missed — the overview states how much of your used space it
actually measured, and names the rest: system volumes, admin-only folders, and folders blocked on
Full Disk Access.
- The Grant access button only appears when a real read of a protected file says the permission is actually missing, so a machine that already granted it never gets nagged again.
- Every number is decimal, so it matches Finder and About This Mac byte for byte.
- The "Other counted" slice adds up — open that row and every place behind the arc is listed under it, and the last line spells the total out part by part (the rows listed, plus the ones under the 100 MB floor), because "a hundred-plus GB, trust me" is not an explanation.
- Large Files — top N across the same roots, dev directories skippable.
- Long Untouched — files you haven't opened in N days, across the same roots.
- Duplicates — size → partial hash → full hash, grouped, the newest copy in each group locked
so you can't nuke the only one.
- Copies that live inside a venv / site-packages / DerivedData never enter the comparison and are listed separately: delete one and that environment is short a piece.
Dev machine specials
- node_modules — project sweep grouped per project, so you see "these 3 checkouts cost 4.7 GB".
- Docker Usage — one row per container runtime actually installed (Docker Desktop, OrbStack, Podman, colima), measured as what its virtual disk takes on this disk, with the engine's own figures listed under it. Read-only: it points at where to prune, it never deletes for you.
Clean up
- App Caches — a curated knowledge base (system caches, crash dumps, WeChat / DingTalk / WeCom / QQ …). Every entry explains what it is, what happens if you delete it, and how to get it back, with a badge saying what deleting costs — Safe, re-downloadable, or data loss.
- Dev Caches — the same knowledge base, the tools half of these machines actually fill the disk with: Homebrew, npm / pnpm / yarn, Maven, Gradle, conda, uv, cargo, Ollama models, Xcode archives, DerivedData and every simulator device listed one by one.
- Leftovers — data orphaned by apps you already uninstalled, matched against the bundle IDs of everything still installed. Under-reports rather than over-deletes.
- Trash — session stats, undo stack, and an Empty button: outside the sandbox it asks Finder to do the emptying, in the App Store build it opens the Trash so you can press ⌘⇧⌫.
Diagnostics & dumps
- Crash dumps — Crashpad folders recognized by structure (
settings.datpluscompleted/pending/new), so any app that has ever crashed lands here on its own, with the host app attributed from the path. Every row carries growth since the previous scan: a red badge for bursts (2,674 dumps in 57 seconds reads back as exactly that), amber for slow accumulation over long gaps. - Trim by retention — the first time the category appears, DiskWise suggests "keep the newest
2,000"; you adopt it or dismiss it. The trim preview is pure math, execution moves the dump
folders to the Trash (
settings.datand the folder skeleton stay), and the batch undoes as a whole. Nothing runs on its own — no daemons, no timers. - Content probe, off by default — opt in, and DiskWise reads the first 64 KB of at most five sample dumps per entry: the crashing executable, the bundle identifier, and any agent session fingerprints in the captured environment. When the folder's owner and the dumps' writer disagree, the row says so. Fingerprints always display redacted, everything stays local, and the privacy policy documents this one exception.
- System reports & Observation —
.ips/.hang/.panicfiles under~/Library/Logs/ DiagnosticReports, plus a read-only list of everything the scan can see but this tool will never touch (system areas, admin-only report folders, look-alike directories it cannot positively identify), each row carrying the reason it is not offered for deletion. Seeing is ungated; deleting is.
Personalize
- Skins — 6 themes, and the interesting part is that they are not color swaps: each one changes typeface, corner radius, elevation, motion signature and chart palette. Morning Fog, Graphite, Mint, Polar Night, Aurora Glass, Ink & Paper — all six are in the box.
- Skins are data, not code — all six live in a single file,
Sources/DiskCleaner/Resources/skins.json, which documents its own fields. A seventh theme is one JSON object: edit that file in the browser on GitHub and open a PR — no Xcode, no build, no Swift.
Screenshots
What the button under the ring opens — a list you tick, then a screen that repeats it back before anything moves:
| Reclaimable list | Confirm |
|---|---|
| Overview | Duplicates |
|---|---|
| Dev Caches | Leftovers |
|---|---|
One page for whole apps — the app itself, plus the folders in your home that provably belong to it. A folder only appears here when it carries the app's bundle ID or a name derived from it:
The skin store renders a live thumbnail of each theme — mini sidebar, ring gauge, rows and buttons, all drawn with that skin's real tokens — so you can see the skeleton before you wear it:
Six skins, six skeletons. Same page, three of them — Graphite is the dark one:
| Graphite | Mint | Polar Night |
|---|---|---|
The UI ships in ten languages — English, Simplified and Traditional Chinese, Japanese, Korean, German, Spanish, French, Russian and Brazilian Portuguese — switchable from the language menu on the Skins page, and following the system language by default. Same screens in Chinese:
| 空间总览 | 开发缓存 |
|---|---|
Counts are inflected per language rather than pasted together in English: Russian picks its own form
for every number (1 файл, 3 файла, 11 групп), German and the Romance languages inflect
singular/plural, and Japanese and Korean use the measure word those languages actually use.
Install
Mac App Store
DiskWise: Storage Cleaner — macOS 13+, free, install it and start using it; the store takes care of every version after that.
Each of those versions has to clear Apple's review first, so the store can trail a GitHub release. If you want the newest build the moment it ships, use Homebrew or the DMG below.
Homebrew
brew tap DreamOfXM/diskwise https://github.com/DreamOfXM/diskwise
brew install --cask dreamofxm/diskwise/diskwise
The cask is Casks/diskwise.rb in this same repository, so the tap has to be pointed at it by
URL: dreamofxm/diskwise on its own would send Homebrew looking for a homebrew-* repository
that does not exist. After the tap, install by the fully-qualified name — since Homebrew 6
non-official taps are untrusted by default, and installing by full name trusts just this cask.
That first tap clones this repository's whole history, roughly 300 MB, so on a slow link it sits
in silence for a while; the DMG it then installs is about 10 MB.
If Homebrew asks for more than that:
brew trust --cask dreamofxm/diskwise/diskwise
brew install --cask diskwise
Tap details and how the pinned checksum gets bumped: docs/homebrew.md.
Homebrew installs the same file the Releases page carries. From v1.7 it is signed with a Developer ID certificate and notarized by Apple, so it opens on a double-click and never reaches that step. Releases before v1.7 were built ad-hoc, so macOS stops the first launch once and you approve it in System Settings → Privacy & Security → Open Anyway (on macOS 13–14, right-click → Open does the same job). Getting it from the Mac App Store skips that step entirely.
DMG
- Download
DiskWise-<version>[-universal].dmgfrom Releases. - Open it and drag DiskWise.app to Applications.
- Double-click it. From v1.7 that just works — the app is Developer ID signed and notarized. On a pre-v1.7 build the first launch gets stopped once; approve it in System Settings → Privacy & Security → Open Anyway and the app opens normally from then on (on macOS 13–14, right-click → Open works instead; Sequoia removed that shortcut).
Releases built with ARCH=universal are named …-universal.dmg and carry both the Apple
Silicon and Intel slices in one file; the Apple Silicon-only ones are named DiskWise-<version>.dmg.
Checksums are published next to each release asset, and the cask pins the same SHA-256.
Build from source
You need the Xcode Command Line Tools — not full Xcode.
swift build # debug
swift run SelfTest # all green is the precondition for shipping
swift run DiskCleaner # run the app
bash build_app/build.sh # localize check → build → self-test → .app → sign → dist/*.dmg + SHA256
build.sh refuses to produce a package if any of the three gates fails: missing translations, a
failing self-test, or an unpacked resource. The translation gate parses the Swift sources and
skins.json itself, so it catches a user-visible string that was never wrapped in L(…) as well as
a missing translation — a language can't silently ship half-translated.
Contributing? Start with CONTRIBUTING.md, then docs/ARCHITECTURE.md and docs/DESIGN.md — both encode rules that were learned the expensive way. Three PRs need no Swift at all: a cache knowledge base entry, a skin, or a translation.
DiskWise MCP questions
Is it safe to use with an AI agent?
Yes, it cannot perform 'rm -rf'; it only moves known-safe items to the Trash, making every operation undoable.
Does it delete files permanently?
No, everything removed is sent to the Trash and can be undone until you manually empty it.
Which AI clients support this server?
It supports Claude Code, Cursor, Codex, Qoder, OpenCode, Zed, ZCode, and Claude Desktop.