# mcp-folder-scout [Health: Active]

**Category:** 📂 File Systems  
**Repository:** https://github.com/dharani0804/mcp-folder-scout  
**GitHub Stars:** 1  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mcp-folder-scout

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

## Tools
Capabilities this server exposes over MCP:

- **scan_folder** — Rollup of a folder: type breakdown, age bands, largest subfolders.
- **list_files** — Individual files filtered by age, size, type, or subfolder.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

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

## Documentation

## 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:

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

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

```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.

_Full upstream README: https://allmcps.com/mcp/mcp-folder-scout/readme_