Skip to main content
Glama
Disk Clean MCP Server

Disk Clean MCP Server

by Kate941-su

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

node_modules, __pycache__, Rust target/, build/ and dist/, Python virtual environments (.venv), ~/.gradle/caches, ~/.cargo/registry

Large, unused videos

.mp4, .mov, .mkv and other videos over 100 MB that have not been opened or changed in 90 days

Old logs

.log and .log.gz files not updated in 30 days

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)

  1. Download the latest diskclean-mcp-server-*.mcpb from Releases

  2. Double-click the file, or drag it into Claude Desktop's Settings → Extensions

  3. 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 | sh

Windows (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.md

Claude Desktop (manual setup)

Open the config file:

OS

Config file

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Windows

%APPDATA%\Claude\claude_desktop_config.json

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

  1. The assistant looks at the folder and tells you what is using the space

  2. You get a list of candidates (path, type, size, last modified) and the total space you can free. Nothing has been moved yet

  3. You say what to move ("all of them", "only node_modules", "everything except #3")

  4. 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_modules and 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, ~/AppData or 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-server

To 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 with which uvx on macOS / Linux or where uvx on Windows

  • In 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

MIT

Available Tools

4 tools
analyze_disk_usageA
Read-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_pathsA
Read-only

OSに応じた代表的なキャッシュ・ログディレクトリのうち、実在するものを返す。 掃除対象の場所をユーザーが指定していないときの候補探しに使う。

Inputs: no named parameters. Returns: os, home, cache_paths

move_to_trashA
DestructiveIdempotent

指定パスをOSのゴミ箱(Trash/Recycle Bin)へ移動する。完全削除はしない。 必ずユーザーの明示的な同意を得てから実行すること。 スキャン結果にないパスや保護パスは skip される。

Inputs: paths (required), scan_id (required). Returns: moved, failed, skipped, moved_mb

scan_cleanup_targetsA
Read-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

    A4/5.0

    Scored across 4 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Official 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 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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 npm
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables an AI assistant to perform read-only scans of Windows drives and identify cleanup candidates, including caches, temporary files, and largest files.
      1
      1
      MIT