Mcp Folder Scout

io.github.dharani0804Published by GitHub account dharani0804v0.1.1Updated Oct 24, 2026

Read-only folder triage: what is in a folder, what is stale, and where the space went.

VerifiedSTDIODesktop onlyFiles & StorageData & Analytics

Overview

AI-generated overview

Read-only MCP server that lets an assistant summarize one local folder: file counts, sizes, age bands, largest subfolders and stale files.

What you can do
  • Scan a folder for a rollup of file types, age bands and largest subfolders
  • List individual files filtered by age, size, type or subfolder
  • Report which files have not been accessed in a long time and where space is concentrated
  • Flag identity, legal, tax and medical files as protected and exclude them from cleanup suggestions
  • Report which folders were skipped, such as cloud-synced, system, app bundle and build directories
When to use it
Useful when you want to understand what is taking up space in a folder, find old or untouched files, or get cleanup suggestions you will act on yourself. It suits one-off triage of a local folder rather than ongoing file management.
Requirements
Runs locally over stdio via uvx; needs uv and Python 3.10 or newer. No accounts, API keys or environment variables are declared. Works with any MCP client, including Claude Desktop via its config file.
Before you install
It returns file names, sizes and timestamps to the assistant, though not file contents. It cannot delete, move or rename anything, so any cleanup is done by you. Access times are unreliable and old files may be important, so review suggestions before deleting. Cloud-synced folders are skipped, and scans stop at 50,000 files and three levels deep by default.

Installation

In SourceWeft

  1. Open Mcp Folder Scout in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

mcp-folder-scout

Ask Claude what's in a folder, what's gone stale, and where the space went.

Points at one folder on your machine and reports names, sizes, and dates. It cannot read file contents, and it cannot move or delete anything.

> What's in my Downloads folder, and what haven't I opened in over a year?
771 files, 43.0 GB. Video is 96% of it.
Not opened in over a year: 102 files, 15.3 GB, almost all of itvideo — Barclay lake (27 clips, ~12 GB) and Big (2 clips, 2.5 GB).If those are backed up elsewhere, they're the obvious candidates.
76 files matched identity, legal, tax, or medical naming and wereexcluded from the suggestions above.

Install

bash
claude mcp add --scope user folder-scout -- uvx mcp-folder-scout

For Claude Desktop, add this to claude_desktop_config.json and restart:

json
{  "mcpServers": {    "folder-scout": {      "command": "uvx",      "args": ["mcp-folder-scout"]    }  }}

The config file lives at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows.

Requires uv and Python 3.10+. Works with any MCP client.

Tools

ToolWhat it does
scan_folderRollup of a folder: type breakdown, age bands, largest subfolders.
list_filesIndividual files filtered by age, size, type, or subfolder.

Both return metadata only.

What it will not do

It cannot delete, move, or rename anything. There is no write path in the code. Suggestions go to you; you act on them yourself in Finder.

It cannot read your files. Only names, sizes, and timestamps leave your machine.

It will not recommend removing your documents. Files and folders matching identity, legal, tax, or medical naming — passport, visa, W2, insurance, marriage, deed, and others — are counted in the totals and marked, but never offered as cleanup candidates. That protection inherits downward, so a file called scan1.pdf inside Passport Renewal/ is covered too.

Cloud-synced folders (iCloud, Dropbox, OneDrive) are skipped rather than handled, because their sizes and timestamps are meaningless on disk. System folders, app bundles, and build directories are skipped too. Every scan reports what it excluded.

Known limits

Last-access time is a hint, not a fact. Spotlight, backups, and antivirus can all bump it, and some volumes stop tracking it entirely. When the server detects that access times aren't being maintained, it says so and falls back to modified dates.

Old and untouched describes archived tax records as accurately as it describes junk. That's what the protected list is for, and it will not catch everything. Review before you delete.

APFS clones and hard links share blocks on disk. Files sharing an inode are counted once, so totals don't double-count, but deleting one copy of a cloned file may free less than its listed size.

Scans stop at 50,000 files and descend three levels by default. Results are cached for five minutes; pass refresh to force a rescan.

Screenshot piles and near-duplicate images are not detected yet. Exact-duplicate detection is planned.

License

MIT

mcp-name: io.github.dharani0804/mcp-folder-scout

mcp-name: io.github.dharani0804/mcp-folder-scout

Source: README.md at commit f6a5917

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.1LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts