Disk Clean MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Disk Clean MCP Server Clean up all the node_modules folders under ~/projects."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Disk Clean MCP Server
日本語 | English
Ask Claude or another AI assistant to "clean up my disk". This MCP server finds the files that eat your disk space and moves them to the trash.
Nothing is deleted. Items go to the OS trash, so you can restore them later
You always see a list first, and only the items you approve are moved
System folders are never touched
Supported OS: macOS / Linux / Windows
What it finds
Type | Examples |
Developer caches |
|
Large, unused videos |
|
Old logs |
|
You can change the size and age limits when you ask (for example "videos over 500 MB" or "logs older than a year").
Related MCP server: mac-disk-cleaner
Install
Claude Desktop (easiest)
Download the latest
diskclean-mcp-server-*.mcpbfrom ReleasesDouble-click the file, or drag it into Claude Desktop's Settings → Extensions
Click Install
Claude Desktop sets up Python and everything else for you.
Other apps (Claude Code, Cline, manual setup)
These use uv to download and run the server. You do not need to install Python yourself.
Step 1. Install uv
macOS / Linux:
curl -LsSf https://astral.sh/uv/install.sh | shWindows (PowerShell):
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"Open a new terminal and check that uv --version works.
Step 2. Add the server to your app
Claude Code
claude mcp add --scope user diskclean -- uvx diskclean-mcp-server--scope user makes it available in every project.
Optional: install the skill that teaches Claude the safe cleanup steps.
mkdir -p ~/.claude/skills/disk-cleanup
curl -fsSL https://raw.githubusercontent.com/Kate941-su/diskcleaner-mcp/main/.claude/skills/disk-cleanup/SKILL.md \
-o ~/.claude/skills/disk-cleanup/SKILL.mdClaude Desktop (manual setup)
Open the config file:
OS | Config file |
macOS |
|
Windows |
|
Add the following and restart Claude Desktop:
{
"mcpServers": {
"diskclean": {
"command": "uvx",
"args": ["diskclean-mcp-server"]
}
}
}Cline (VS Code)
Open the config file from Cline's MCP Servers screen and add the same entry as above.
How to use
Ask your assistant in plain words:
My disk is full. Find files I don't need in my home folder.Clean up all the node_modules folders under ~/projects.Find videos in ~/Movies over 1 GB that I haven't watched in six months.Show me what is using space in ~/Library/Caches, two levels deep.What happens
The assistant looks at the folder and tells you what is using the space
You get a list of candidates (path, type, size, last modified) and the total space you can free. Nothing has been moved yet
You say what to move ("all of them", "only node_modules", "everything except #3")
Only the approved items go to the trash, and you get a report
Restoring files
Everything goes to the trash, so you can bring it back at any time.
macOS: open the Trash in Finder, right-click the item and choose Put Back
Windows: open the Recycle Bin, right-click the item and choose Restore
Linux: open the trash in your file manager and choose Restore (stored in
~/.local/share/Trash)
Disk space is actually freed when you empty the trash.
What is never moved
OS system folders (
/usr,/System,C:\Windows,C:\Program Files, and so on)Your home folder itself, and folders directly under the disk root
Anything that was not in the list you were shown
Symbolic links (and the files they point to)
node_modulesand virtual environments that belong to tools and apps, not to your projects: the pnpm store, Node.js installed by nvm, VS Code extensions, and anything inside~/Library,~/AppDataor hidden folders in your home folder. Removing these would break the tool
build/ and dist/ only count as caches when a build file such as package.json sits next to them, so normal folders with the same name are not picked up by mistake.
Updating
The Claude Desktop extension: download the new .mcpb from Releases and install it again.
With uvx: uv keeps a cached copy. To get the latest version, run the following and restart your app.
uv cache clean diskclean-mcp-serverTo always start the newest version, use "args": ["diskclean-mcp-server@latest"] instead. This checks for updates every time the server starts.
Troubleshooting
The tools don't show up in my assistant
Restart the app after changing settings
Claude Desktop may not find
uvx. Put the full path in"command". Find it withwhich uvxon macOS / Linux orwhere uvxon WindowsIn Claude Code, check with
claude mcp list
"Some folders could not be read" (skipped_errors)
Folders you don't have permission to read are skipped. On macOS, giving the app Full Disk Access may help (System Settings → Privacy & Security)
The scan stopped early (timed_out)
One scan runs for up to 60 seconds. Ask for a smaller folder, such as
~/projects
For developers
See docs/DESIGN.md for the design, tool specs, development setup and release process (in Japanese).
License
Available Tools
4 toolsanalyze_disk_usageARead-only
指定ディレクトリ配下の容量内訳を返す(読み取りのみ)。 カテゴリ別合計(dev_cache/video/log/other)と、深さ max_depth までのエントリのうち 大きい順の上位を含む。各エントリのサイズは配下の合計なので、親子のサイズは重複する。 どこが大きいか分かったら、そのパスを指定して再度呼ぶと効率よく掘り下げられる。
Inputs: target_path (required), max_depth. Returns: total_mb, timed_out, entry_count, target_path, +3 more
get_os_env_pathsARead-only
OSに応じた代表的なキャッシュ・ログディレクトリのうち、実在するものを返す。 掃除対象の場所をユーザーが指定していないときの候補探しに使う。
Inputs: no named parameters. Returns: os, home, cache_paths
move_to_trashADestructiveIdempotent
指定パスをOSのゴミ箱(Trash/Recycle Bin)へ移動する。完全削除はしない。 必ずユーザーの明示的な同意を得てから実行すること。 スキャン結果にないパスや保護パスは skip される。
Inputs: paths (required), scan_id (required). Returns: moved, failed, skipped, moved_mb
scan_cleanup_targetsARead-only
条件に一致する削除候補をサイズの大きい順に列挙する(Dry-Run。何も削除しない)。 返された scan_id は move_to_trash に必要。結果はユーザーに提示して同意を得ること。
Inputs: target_path (required), target_type (required), max_results, min_size_mb, +2 more. Returns: items, scan_id, timed_out, truncated, +6 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool targets a distinct stage: env-path discovery, read-only size analysis, dry-run candidate scanning, and the actual trash move. analyze_disk_usage and scan_cleanup_targets both traverse directories and return sizes, which could be momentarily confused, but the descriptions clearly separate breakdown analysis from deletion-candidate listing with the required scan_id.
All four tools follow the same snake_case verb_noun convention (get_os_env_paths, analyze_disk_usage, scan_cleanup_targets, move_to_trash). Verb choice is descriptive and consistent across the set.
Four tools is on the lean side but each maps to a necessary step in the cleanup workflow with no redundancy. A slightly richer surface (e.g. trash listing/restore) would round it out, but nothing here feels superfluous.
The core lifecycle (discover candidate locations → analyze sizes → scan for deletable items → move to trash with consent) is fully covered, including a safety-first dry-run step. Gaps exist around undo/restore-from-trash and inspection of what was moved, but agents can work around these with OS-level operations.
Maintenance
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 gradedqualityBmaintenanceOfficial server for the ShieldFive end-to-end encrypted vault. Moves files off your computer into the vault, reading each copy back and verifying it before the original goes to a local trash folder (nothing deleted). Also finds duplicates by content and tidies folders. Decrypts on your machine; access is scoped, expiring, revocable and undoable.60 npmMIT- 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
- AlicenseNot gradedqualityCmaintenanceEnables an AI assistant to measure macOS disk usage, investigate unfamiliar files and folders, identify cleanup candidates, and prepare numbered cleanup proposals that move approved items to the Trash only after server-side path checks.16 npm1MIT
- AlicenseAqualityCmaintenanceEnables an AI assistant to perform read-only scans of Windows drives and identify cleanup candidates, including caches, temporary files, and largest files.11MIT