diskclean-mcp
MCP server that wraps diskclean.sh, letting agents like Claude Desktop, Claude Code, or any MCP client scan and clean a Mac's reclaimable disk space — with safety guardrails built into the protocol itself.
Heads-up:
0.2.0is a breaking change vs0.1.x. The destructiveclean_items()tool was replaced by a three-step flow (scan_disk→prepare_cleanup→execute_cleanup) so an agent literally cannot delete anything without first surfacing a plan to the user. See Safety model.
Tools exposed
| Tool | Type | Notes |
|---|---|---|
scan_disk() |
Read-only | Returns { scan_id, disk, items: [...] }. scan_id valid 5 min. |
prepare_cleanup(scan_id, ids, mode, confirm_risky, i_understand_deletion_is_permanent) |
Read-only | Builds a plan, returns confirmation_token + warnings. Deletes nothing. |
execute_cleanup(confirmation_token, i_have_user_consent, i_understand_large_cleanup) |
Destructive | One-shot. Consumes the token. |
disk_status() |
Read-only | Cheap df check. |
Quick start
uvx diskclean-mcp
That's it — zero install. The server runs on stdio, ready for any MCP client.
Add to Claude Code
claude mcp add diskclean -- uvx diskclean-mcp
Add to Claude Desktop
{
"mcpServers": {
"diskclean": {
"command": "uvx",
"args": ["diskclean-mcp"]
}
}
}
Safety model
The destructive execute_cleanup is gated by four independent guardrails:
| Guardrail | Triggered by | Required override |
|---|---|---|
| Scan binding | always | scan_id from a recent scan_disk() (≤ 5 min old) |
| Plan token | always | confirmation_token from prepare_cleanup() — one-shot, ≤ 5 min |
| User consent | always | i_have_user_consent=True (the agent's accountability flag) |
| Permanent delete | mode="delete" |
i_understand_deletion_is_permanent=True (set in prepare_cleanup) |
| Risky items | items with risk="risky" |
confirm_risky=True (else excluded from plan) |
| Large cleanup | total > 5 GB | i_understand_large_cleanup=True |
Why this matters: an agent that's prompt-injected, buggy, or sloppy cannot delete anything by calling a single tool. It has to:
- Call
scan_disk()→ store thescan_id. - Call
prepare_cleanup()with the chosen IDs and any required acknowledgments. Get back aconfirmation_tokenand warnings. - Present the plan and warnings to the user.
- Get explicit consent.
- Call
execute_cleanup()withi_have_user_consent=True.
Failing to follow this protocol returns clear ValueErrors with remediation hints, all of which are logged. The flags have intentionally long, explicit names so any spurious =True in a transcript is obvious in review.
Audit log
Every scan, prepare, execute, and rejection is logged as JSON Lines to:
~/Library/Logs/diskclean-mcp.log
Sample entry:
{"ts":"2026-05-26T22:15:30Z","event":"execute","token":"abc...","scan_id":"def...","ids":["xcode-deriveddata"],"mode":"trash","summary":{"succeeded":1,"failed":0,"skipped":0,"space_freed_bytes":30543958016}}
After-the-fact forensics: tail -f ~/Library/Logs/diskclean-mcp.log | jq.
Dev install (from this repo)
cd mcp/
uv venv
uv pip install -e ".[dev]" # includes pytest
uv run pytest # run the safety guardrail tests
diskclean-mcp # run the server on stdio
To register the local server with Claude Code:
claude mcp add diskclean -- uv --directory /absolute/path/to/repo/mcp run diskclean-mcp
Configuration
| Env var | Purpose |
|---|---|
DISKCLEAN_SCRIPT |
Override the path to diskclean.sh (otherwise auto-discovered: bundled in wheel, or sibling of mcp/ in dev). |
How it works
agent → MCP → server.py → bash diskclean.sh --json | --execute → JSON → server.py → MCP → agent
↓
~/Library/Logs/diskclean-mcp.log (audit trail)
The bash script is the single source of truth for scanning logic and the actual destructive operations. The Python layer adds:
- Protocol-level state (scan_id, confirmation_token)
- Consent enforcement
- Audit logging
- Friendly error messages with remediation hints
Adding a new scan category means editing diskclean.sh only — the MCP server picks it up automatically.
License
MIT — same as the parent project.
Metadata
Release files for diskclean-mcp 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| diskclean_mcp-0.2.0.tar.gz | 21.1 kB | Without provenance | Details for diskclean_mcp-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| diskclean_mcp-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for diskclean_mcp-0.2.0-py3-none-any.whl |
Total release size: 41.1 kB
Release files / diskclean_mcp-0.2.0.tar.gz
| Download URL | diskclean_mcp-0.2.0.tar.gz |
|---|---|
| Size | 21.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4f49213c5e3001c252449a2d3af6235e91b5d785470dd05d76ed2348533ca714
|
|
BLAKE2b-256 checksum How to use checksums |
d6ebf47d50694ce9327309e821d9470d6ed76886a99df9c646a948044320bac5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.6.13
|
Release files / diskclean_mcp-0.2.0-py3-none-any.whl
| Download URL | diskclean_mcp-0.2.0-py3-none-any.whl |
|---|---|
| Size | 20.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2f3db719033fbe318e61383cddff01b08d2a5b63cf6c3a1fa34d9e494aa0d22b
|
|
BLAKE2b-256 checksum How to use checksums |
b29f3e1265ad75eb3e07705a15383fec8db6cee3bb2f62968673227a6f0ca39b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.6.13
|
Security for diskclean-mcp 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.