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: mcp-server-mint

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

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

See 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 Trash

A 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 report

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

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

Cleanup tiers

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 .next in 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.json maps 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 detectors argument to analyse.

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 review tier 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_trash requires a list token and confirm: 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 test

The 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

MIT