MCP server for disk cleanup

Find out what is filling your drive, and fix it.

diskscout-mcp lets your AI assistant scan drives, rank the biggest folders and files, and clear safe-to-delete caches. You approve every change.

Install View on GitHub

git clone https://github.com/ToxinNozaki/diskscout-mcp.git && cd diskscout-mcp && npm install

AppData84 GB

VirtualBox VMs61 GB

.gradle22 GB

Temp9 GB

Downloads31 GB

Steam26 GB

node_modules14 GB

Illustrative example of what a scan surfaces. Numbers are made up.

How it works

Disk analyzers are built for people to look at. This one is built for an assistant to call, so you can just ask.

Scan once, ask anything

A parallel scanner measures a folder or whole drive and keeps the result in memory. Follow up questions are instant.

Real numbers

Biggest folders with their share of the total, biggest files, and filters for file type, age and size. No guessing.

Cleanup with guard rails

Known cache locations come with risk levels. Every change is a dry run first, and protected locations are refused in code.

You

My C drive is almost full. Find out why and help me fix it.

Claude

C: is 96% full with 18 GB free. The biggest folders are AppData (84 GB), VirtualBox VMs (61 GB) and .gradle (22 GB). I found 14.2 GB of caches that are safe to clear. Want me to start with the browser and npm caches?

list_drives, scan_folder, top_folders, cleanup_candidates

You

Yes, do a dry run first.

Illustrative conversation.

Install

Requires Node.js 22 or newer. Windows, macOS and Linux.

Get the code

git clone https://github.com/ToxinNozaki/diskscout-mcp.git
cd diskscout-mcp
npm install

npm install also builds the server. Run npm test if you want to verify it.

Register it with your client

Claude Desktop

{
  "mcpServers": {
    "diskscout": {
      "command": "node",
      "args": ["C:\\path\\to\\diskscout-mcp\\dist\\src\\index.js"]
    }
  }
}

Add to %APPDATA%\Claude\claude_desktop_config.json and restart.

Claude Code

claude mcp add diskscout -- node C:\path\to\diskscout-mcp\dist\src\index.js

Other clients: run node dist/src/index.js. It speaks MCP over stdio.

Ask

Try: "Scan my C drive and tell me what is using the most space."

Tools

15 tools. This reference is generated from the code, so it always matches the server.

`list_drives`

Read only

Show every drive with total, used and free space. Start here to see which drive is filling up.

`scan_folder`

Read only

Scan a folder or whole drive and remember the result so other tools answer instantly. Large drives can take a few minutes. The call waits up to wait_seconds, then reports progress. Call it again with the same path to keep waiting or to read the result. Read only.

path string required: Folder or drive to scan, for example C:\ or C:\Users\me\AppData. Use ~ for the home folder.
wait_seconds integer default 30: How long to wait for the scan before returning progress. 0 starts the scan and returns immediately.
rescan boolean default false: Ignore saved results and scan again.
engine string default "auto": Scan engine. auto picks the fastest one that works (robocopy on Windows). Use node to compare or if results look wrong.

`top_folders`

Read only

List the biggest folders inside a scanned path, largest first, with each folder's share of the total. Needs a finished scan that covers the path. Read only.

path string required: Folder to look inside. Must be inside a scanned location.
depth integer default 1: How many levels down to include. 1 lists direct sub folders only.
limit integer default 25: Maximum rows to return.
min_size_mb number default 0: Hide folders smaller than this many MB.

`top_files`

Read only

List the largest files in a scanned path, optionally filtered by extension, age or minimum size. Only the 5000 largest files of each scan are kept, so small file filters may return fewer rows than asked. Needs a finished scan. Read only.

path string optional: Limit to files below this folder. Defaults to the most recent scan.
limit integer default 25: Maximum rows to return.
extensions string[] optional: Only these file types, for example [".iso", ".zip"].
older_than_days number optional: Only files not modified for at least this many days.
min_size_mb number default 0: Hide files smaller than this many MB.

`cleanup_candidates`

Read only

Measure well known places that are normally safe to clear: temp folders, browser and package manager caches, crash dumps and similar. Each result has a risk level (safe, caution, review, system) and an id. Items marked clearable can be emptied with clear_cleanup_target. Does not need a scan. Read only.

min_size_mb number default 50: Hide targets smaller than this many MB.

`clear_cleanup_target`

Changes files

Permanently delete the contents of one clearable target from cleanup_candidates, for example user-temp or npm-cache. The folders are kept, only what is inside is removed. Files in use are skipped. Defaults to a dry run that only reports what would happen. Only ids from cleanup_candidates are accepted.

id string required: Target id from cleanup_candidates, for example user-temp.
dry_run boolean default true: When true nothing is deleted. Set to false only after the user agreed.

`move_to_recycle_bin`

Changes files

Send specific files or folders to the Windows Recycle Bin. Windows only. System folders, drive roots and standard user folders are refused. Defaults to a dry run. Space is only freed after the Recycle Bin is emptied, and Windows may delete items larger than the Recycle Bin limit permanently, so check sizes first.

paths string[] required: Exact absolute paths of files or folders. No wildcards.
dry_run boolean default true: When true nothing is moved. Set to false only after the user agreed to this exact list.

`find_dev_artifacts`

Read only

Find folders that projects can rebuild: node_modules, Python virtual environments and caches, Gradle, Next.js and similar build caches. Shows size, how long since each was touched and how to restore it. Needs a finished scan. Read only. To remove one, use move_to_recycle_bin.

path string optional: Limit to this folder. Defaults to the most recent scan.
min_size_mb number default 50: Hide folders smaller than this many MB.
older_than_days number optional: Only folders not modified for at least this many days.
limit integer default 40: Maximum rows to return.

`find_folders`

Read only

Find folders by name anywhere in a scanned path, with sizes. Names are case insensitive and may use * and ? wildcards, for example ["cache*", "temp"]. Needs a finished scan. Read only.

names string[] required: Folder names or patterns to look for.
path string optional: Limit to this folder. Defaults to the most recent scan.
min_size_mb number default 0: Hide folders smaller than this many MB.
older_than_days number optional: Only folders not modified for at least this many days.
limit integer default 30: Maximum rows to return.

`find_duplicates`

Read only

Find identical large files among the biggest files of a scan. Files are grouped by size, then compared by content hash, so this reads file contents. Needs a finished scan. Stops after about 40 seconds and says so. Read only. Review the groups before removing any copy.

path string optional: Limit to this folder. Defaults to the most recent scan.
min_size_mb number default 10: Ignore files smaller than this many MB.
limit integer default 20: Maximum duplicate groups to return.

`save_snapshot`

Read only

Save the folder sizes of a finished scan to disk so a later scan can be compared against it. Keeps folders of 10 MB or more, four levels deep. Stored in ~/.diskscout/snapshots. Writes one small file, never touches your data.

path string optional: Scanned folder to snapshot. Defaults to the most recent scan.
name string optional: Name for the snapshot. Defaults to the folder and the date.

`compare_snapshot`

Read only

Show which folders grew or shrank since a saved snapshot. Needs a fresh finished scan that covers the snapshot's folder. Call without a name to list saved snapshots. Read only.

name string optional: Snapshot name. Leave out to list snapshots.
min_change_mb number default 50: Hide changes smaller than this many MB.
limit integer default 20: Maximum rows per direction.

`recycle_bin_info`

Read only

Show how many items are in the Windows Recycle Bin and roughly how much space they use. Windows only. Read only.

`empty_recycle_bin`

Changes files

Permanently empty the Windows Recycle Bin on all drives. Items cannot be recovered afterwards. Windows only. Defaults to a dry run that only reports what is in it. Set dry_run to false only after the user agreed.

dry_run boolean default true: When true nothing is deleted.

`scan_status`

Read only

List the scans held in memory with their progress, speed and age. Optionally cancel a running scan. Read only apart from cancelling.

cancel_path string optional: Root path of a running scan to cancel.

Safety

Cleanup is where a tool like this can do harm, so the rules are enforced in code.

Guarantee	How
Nothing changes by accident	Both cleanup tools default to a dry run. A real change needs `dry_run: false`.
System locations are untouchable	Drive roots, Windows, Program Files, the Recycle Bin, your profile folder and the standard user folders are refused, along with any folder that contains one.
Your files are recoverable	`move_to_recycle_bin` never deletes permanently.
Permanent deletion is narrow	`clear_cleanup_target` only accepts built in ids for temp folders and caches, and keeps the folders. Downloads and system files are never clearable.
No surprises from links	Symlinks and junctions are skipped, never followed.
Everything is logged	Real changes are appended to `~/.diskscout/actions.log`.
Emptying the Recycle Bin is deliberate	`empty_recycle_bin` is permanent, so it defaults to a dry run and needs `dry_run: false`.
Files are only read to find duplicates	Only `find_duplicates` opens files, to hash them. Everything else uses names, sizes and dates.

FAQ

Why not just use WinDirStat, WizTree or Folder Size?

Use them if you like looking at a screen. This project exists so an assistant can answer "why is my drive full" and run the cleanup with you, without clicking through a GUI. They complement each other.

Why does a OneDrive folder look huge?

Online only files report their full size but take almost no local space. Scans use logical file sizes, so cloud placeholders can inflate a folder compared with space actually used on disk.

Why are some items listed as unreadable?

The scan runs with your user permissions. Protected system folders are counted as unreadable and their size is not included. Run your MCP client as administrator if you need them.

Does moving files to the Recycle Bin free space?

Only after you empty it. Windows may also delete items larger than the bin's limit permanently, so the dry run shows sizes first.

Does it read my files?

Only the duplicate finder opens files, to compare their contents. Everything else uses names, sizes and modified dates.

How fast is a full drive scan?

On Windows it uses robocopy in list mode, which reads sizes from directory listings without opening files, split across folders and run in parallel. It falls back to a standard engine if anything looks wrong. Each scan reports its engine and files per second. The scan runs in the background and reports progress, so your assistant can wait and check back.

Why is the folder count sometimes a little different between engines?

The fast Windows engine does not list empty folders. File counts and sizes match the standard engine.