MCP Folder Scout

What mcp-folder-scout does

The mcp-folder-scout MCP server provides read-only folder triage through two MCP tools. It reports file names, sizes, timestamps, type groupings, age ranges, and folder-level storage totals. It does not open file contents, and it has no operation for deleting, moving, or renaming files.

The server also marks files and folders whose names suggest identity, legal, tax, or medical material. These items remain included in totals but are not presented as cleanup candidates. The protection applies to nested files inside matching folders as well. This safeguard is based on naming patterns and is not guaranteed to identify every sensitive document.

Cloud-synced locations such as iCloud, Dropbox, and OneDrive are skipped. System folders, application bundles, and build directories are skipped too, and each scan reports exclusions.

How it works

The mcp-folder-scout MCP server runs locally and examines metadata for a folder selected through the MCP interaction. scan_folder produces an aggregate view, including type breakdowns, age bands, and the largest subfolders. list_files provides file-level results when you need to inspect matches by age, size, type, or subfolder.

Results are cached for five minutes. Passing refresh forces a new scan. Scans stop after 50,000 files and descend three levels by default. Shared inodes are counted once, which prevents APFS clones and hard links from inflating totals, although the displayed size may not equal the space recovered by deleting one copy.

Access time is only an estimate. Spotlight, backups, antivirus software, or filesystem settings can update it, and some volumes do not maintain it. When access times are unavailable, the server reports that condition and uses modification dates instead.

Setup and configuration

Install uv and use Python 3.10 or newer. For Claude Code, add the server with:

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

For Claude Desktop, add a folder-scout entry to claude_desktop_config.json:

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

Restart Claude Desktop after changing its configuration. On macOS, the file is under ~/Library/Application Support/Claude/claude_desktop_config.json; on Windows, it is under %APPDATA%\Claude\claude_desktop_config.json. No environment variables are specified in the provided setup instructions.

Tools and capabilities

• scan_folder: Summarizes a folder by file type, age range, and largest subfolders.
• list_files: Lists matching files using age, size, type, or subfolder filters.
• Metadata-only inspection using names, sizes, and dates.
• Five-minute result caching with an optional refresh rescan.
• Reporting of skipped locations and excluded content.

Limitations and notes

The mcp-folder-scout MCP server suggests candidates for review but does not perform cleanup. Old files may be valuable archives, and the protected-name rules cannot identify every sensitive file, so review results before taking action.

It does not currently detect screenshot piles, near-duplicate images, or exact duplicates. The default depth and 50,000-file scan limit can also affect coverage. Cloud-synced and system-managed locations are intentionally excluded rather than analyzed.