A
licenseB
qualityC
maintenanceEnables read-only analysis of local disk usage to identify cleanup targets by size, type, recency, and duplicates.
6
14 npm
1
MIT
mcp-folder-scout
by dharani0804
mcp-folder-scout
Pregunta a Claude qué hay en una carpeta, qué se ha quedado obsoleto y a dónde ha ido a parar el espacio.
Apunta a una carpeta de tu máquina e informa de nombres, tamaños y fechas. No puede leer el contenido de los archivos ni puede mover o eliminar nada.
> 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 it
video — 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 were
excluded from the suggestions above.Instalación
claude mcp add --scope user folder-scout -- uvx mcp-folder-scoutPara Claude Desktop, añade esto a claude_desktop_config.json y reinicia:
{
"mcpServers": {
"folder-scout": {
"command": "uvx",
"args": ["mcp-folder-scout"]
}
}
}El archivo de configuración se encuentra en ~/Library/Application Support/Claude/claude_desktop_config.json en macOS y en %APPDATA%\Claude\claude_desktop_config.json en Windows.
Requiere uv y Python 3.10+. Funciona con cualquier cliente MCP.
Related MCP server: WinDirStat MCP Server
Herramientas
Herramienta | Qué hace |
| Resumen de una carpeta: desglose por tipo, bandas de antigüedad y subcarpetas más grandes. |
| Archivos individuales filtrados por antigüedad, tamaño, tipo o subcarpeta. |
Ambas devuelven únicamente metadatos.
Lo que no hará
No puede eliminar, mover ni renombrar nada. No hay ninguna ruta de escritura en el código. Las sugerencias van dirigidas a ti; las ejecutas tú mismo en Finder.
No puede leer tus archivos. Solo los nombres, los tamaños y las marcas de tiempo salen de tu máquina.
No recomendará eliminar tus documentos. Los archivos y carpetas cuyo nombre coincide con denominaciones de identidad, legales, fiscales o médicas (pasaporte, visado, W2, seguro, matrimonio, escritura, etc.) se contabilizan en los totales y se marcan, pero nunca se ofrecen como candidatos de limpieza. Esa protección se hereda a los niveles inferiores, así que un archivo llamado scan1.pdf dentro de Passport Renewal/ también está cubierto.
Las carpetas sincronizadas con la nube (iCloud, Dropbox, OneDrive) se omiten en lugar de procesarse, porque sus tamaños y marcas de tiempo no tienen sentido en el disco. También se omiten las carpetas del sistema, los paquetes de aplicaciones y los directorios de compilación. Cada escaneo informa de lo que se ha excluido.
Limitaciones conocidas
La fecha del último acceso es una pista, no un dato fidedigno. Spotlight, los backups y el antivirus pueden modificarla, y algunos volúmenes pueden dejar de registrarla por completo. Cuando el servidor detecta que los tiempos de acceso no se están manteniendo, lo comunica y recurre a las fechas de modificación.
«Antiguo y sin tocar» describe los registros fiscales archivados con la misma precisión que la basura. Ese es el propósito de la lista protegida, y no lo atrapará todo. Revisa antes de eliminar.
Los clones APFS y los enlaces físicos (hard links) comparten bloques en el disco. Los archivos que comparten inodo se cuentan una sola vez, por lo que los totales no se duplican; sin embargo, eliminar una copia de un archivo clonado puede liberar menos espacio que el indicado en su tamaño.
Los escaneos se detienen en 50 000 archivos y descienden tres niveles por defecto. Los resultados se almacenan en caché durante cinco minutos; pasa refresh para forzar un nuevo escaneo.
Los montones de capturas de pantalla y las imágenes casi duplicadas aún no se detectan. La detección de duplicados exactos está prevista.
Licencia
MIT
Available Tools
2 toolslist_filesA
List individual files in a folder, filtered by age, size, type, or subfolder.
Use after scan_folder to see the actual files behind a summary line, for example the ones not opened in over a year, or the largest videos.
Each row is: age since last opened, size, and path relative to the folder. A leading asterisk marks a protected file (identity, legal, tax, or medical naming). Report those if the user asked to see them, but never put them forward as something to delete or move.
Returns metadata only. This tool never reads file contents.
path: absolute path to the folder. not_opened_days: only files untouched for at least this many days. 0 for all. min_size_mb: only files at least this large. 0 for all. file_type: one of documents, spreadsheets, images, video, audio, archives, installers, code, other. Or a bare extension such as png. Empty for all. subfolder: restrict to one immediate subfolder by name. Empty for all. sort_by: size, oldest (least recently opened), or newest. Default size. limit: rows to return, capped at 100. Default 25.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| limit | No | ||
| sort_by | No | size | |
| file_type | No | ||
| max_depth | No | ||
| subfolder | No | ||
| min_size_mb | No | ||
| not_opened_days | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A4.8/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the behavioral-disclosure burden, and it does so well: 'Returns metadata only. This tool never reads file contents.' It also discloses an important edge case: protected files are flagged with an asterisk and must never be suggested for deletion or moving. That is exactly the kind of behavior an agent needs to know.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is information-dense without being bloated. Every block served a clear purpose: what the tool does, when to use it, row format, protected-file caveat, safety guarantee, and parameter meanings. The transition to parameters is efficient and the usage guidance is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool's output schema relieves it from covering the return shape, and the description covers the workflow context, row layout, and protected-file handling. The main completeness gap is the undocumented 'max_depth' parameter, which could affect the scope of a listing and deserves clarification.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While schema description coverage is 0%, the description adds substantial semantics for most parameters: defaults, unit semantics for 'not_opened_days' and 'min_size_mb', allowed categories for 'file_type', and the cap at 100 for 'limit'. However, 'max_depth' appears in the schema but is not described at all, so the compensation is incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and a clear resource ('individual files in a folder'), then enumerates the four filters: age, size, type, and subfolder. It distinguishes itself from scan_folder by positioning itself as the drill-down step 'to see the actual files behind a summary line'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly tells the agent when to use this tool: 'Use after scan_folder to see the actual files behind a summary line.' It even gives concrete examples, such as 'the ones not opened in over a year, or the largest videos,' which makes the selection condition unambiguous relative to its sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
scan_folderA
Summarize a folder: what dominates it, how old everything is, and where the bulk sits.
Call this first. It returns a rollup rather than a file list, so it stays cheap on folders with tens of thousands of files. Follow with list_files to see individual files matching whatever the summary suggests is worth looking at.
Two things to keep in mind. Size does not imply disposability: large media is often what the user most wants to keep, so age matters more than size. And files matching identity, legal, tax, or medical naming are counted here but marked protected; never suggest removing them.
Cloud-synced folders, system folders, app bundles, and build directories are excluded; the output reports how many were skipped.
path: absolute path to the folder, for example /Users/you/Downloads max_depth: how many levels of subfolder to descend. Default 3.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| max_depth | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries full behavioral disclosure. It states the tool returns an aggregated rollup, remains cheap for large folders, skips specific folder types and reports how many were skipped, and counts protected files without exposing them as removable. This goes well beyond the input schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficient, with the primary purpose captured in a single opening sentence, added guidance in short dense paragraphs, and parameter documentation at the end. Every sentence contributes a concrete behavioral or usage detail; there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and sibling list_files is named, the description provides all necessary context: when to invoke it, what to do after, what is excluded, how protected files are handled, and full parameter semantics. An agent has enough to select and invoke it correctly without further inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate fully, and it does. It explains path with a realistic example and describes max_depth as 'how many levels of subfolder to descend' along with its default, which gives an agent actionable meaning beyond the bare schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Starts with a specific verb-resource pairing, 'Summarize a folder', and names what is summarized: what dominates, how old the contents are, and where data sits. It also distinguishes itself from the sibling list_files by stating it returns a rollup rather than a file list, so an agent can tell which tool fits.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description is explicit: 'Call this first' and 'Follow with list_files' to inspect what the summary flags. It also gives rejection criteria — protected files should never be suggested for removal and certain folders are excluded — making usage boundaries and downstream actions clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
2 tool updates
v0.1.0- First observed
list_files - First observed
scan_folder
TDQS
A4.9/5.0
Scored across 2 tools
Disambiguation5/5
scan_folder and list_files have cleanly distinct purposes: one summarizes the whole folder, the other enumerates specific files. They form a clear two-step workflow with no boundary ambiguity.
Naming Consistency5/5
Question: scan_folder and list_files both follow a predictable verb_noun snake_case pattern, with imperative verbs and noun objects. Naming styles are perfectly aligned across both tool names.
Tool Count4/5
Question: two tools is a bit below the typical robust set size, but for a metadata-only folder inspector the prior pair covers the two natural tasks at equal scope, so the count is reasonable.
Completeness5/5
The domain is folder inspection, and the set covers both approximate information: list_files lets you go from a summary clue to the difficult actual matching set. The two tools form a complete read-only scanning lifecycle.
Maintenance
ActivitySlowing
ResponsivenessNo issues
Related MCP Connectors
Safe folder access for ChatGPT and Claude: read, write and search files, risky tools opt-in.
Search photos and video moments by visual meaning, people, dates, and folders across local libraries, Apple Photos, and OneDrive. Manage collections, groups, favorites, people, and duplicate review. Synced metadata remains searchable while the desktop is offline; local and Apple Photos media access needs the owning device online with remote access enabled. OneDrive media can be accessed directly from the cloud. OAuth or Bearer API keys. Paid Cloud Access required; hosted visual search uses prepaid credits. Text-in-image search is semantic matching, not guaranteed exact OCR. Setup: https://organizewith.ai/en/guides/connect-ai-assistants
Manage files and folders directly from your workspace. Read and write files, list directories, cre…
Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables real-time Windows storage analysis, deep folder scanning, safety tiering, and protected cleanup operations through natural language.41MIT
- AlicenseNot gradedqualityBmaintenanceEnables natural-language queries about disk usage by driving WizTree scans and analyzing cached CSV snapshots. Users can find large files, duplicate data, folder breakdowns, and more without repeatedly rescanning the disk.15MIT
- FlicenseAqualityCmaintenanceEnables read-only analysis of local unstructured documents by scanning a folder, extracting text and structural metadata, and passing content with truncation and error-awareness to an LLM for summarization.91-