File Organizer MCP
File Organizer MCP Server
Versión 3.5.0 | Protocolo MCP 2024-11-05 | Node.js 18+
Un servidor MCP (Model Context Protocol) que organiza archivos. Proporciona a un asistente estilo Claude una única operación atómica para categorizar, ordenar, deduplicar y renombrar archivos, en lugar de encadenar docenas de llamadas primitivas read, write y rename.
Por qué
Un servidor MCP de sistema de archivos basado únicamente en read, write, make y delete obliga a un asistente a planificar cada movimiento y renombrado como un paso separado. Cada paso cuesta tokens, y más pasos significan más posibilidades de equivocarse en la ruta.
File Organizer MCP reemplaza esas cadenas con una sola llamada:
Enfoque primitivo | File Organizer MCP |
Muchas llamadas |
|
Decenas de pasos de razonamiento | Un solo paso de razonamiento |
Alto uso de tokens | Uso mínimo de tokens |
Fácil de corromper en fallos parciales | Operaciones seguras con reversión |
Related MCP server: MCP Filesystem Agent v3
Inicio rápido
Configuración con un comando
npx file-organizer-mcp --setupEl asistente detecta los clientes de IA instalados (Claude Desktop, Cursor, Windsurf, Cline y otros), los configura y te guía en la selección de carpetas y preferencias.
Requisitos
Node.js 18 o superior.
Después de la configuración
Puedes pedirle al asistente cosas como:
"Organiza mi carpeta de Descargas"
"Encuentra archivos duplicados en mis Documentos"
"Muéstrame mis archivos más grandes"
Métodos de instalación
Método | Comando | Caso de uso |
npx |
| Uso ocasional o prueba |
Global |
| Uso regular, inicio más rápido |
Características
Categorización en 12 o más tipos de archivo.
Organización automática basada en cron y modo de vigilancia de directorios.
Detección de duplicados mediante hash de contenido SHA-256.
Extracción de metadatos: EXIF para fotos, ID3 para audio, extracción de temas para documentos.
Organización inteligente que elige la estrategia adecuada por tipo de archivo.
Vista previa en seco, movimientos atómicos y reversión.
Protección contra recorrido de rutas, mitigación de TOCTOU y limpieza de metadatos.
Windows, macOS y Linux.
Herramientas
Herramientas principales
file_organizer_scan_directory- Lista un directorio con información detallada de archivos.directoryes obligatorio;include_subdirsactiva la recursión.file_organizer_read_file- Lee un archivo con validación de ruta de 8 capas.pathes obligatorio;encodingpuede ser utf-8, base64 o binario.file_organizer_organize_smart- Maneja música, fotos y documentos en una sola pasada, eligiendo la mejor estrategia por archivo.file_organizer_batch_rename- Renombra muchos archivos por patrón, regex o numeración.file_organizer_undo_last_operation- Revierte la organización más reciente.
Lista completa de herramientas
file_organizer_analyze_duplicatesfile_organizer_batch_read_filesfile_organizer_categorize_by_typefile_organizer_delete_duplicatesfile_organizer_find_duplicate_filesfile_organizer_find_largest_filesfile_organizer_get_categoriesfile_organizer_inspect_metadatafile_organizer_list_filesfile_organizer_list_watchesfile_organizer_organize_by_contentfile_organizer_organize_filesfile_organizer_organize_musicfile_organizer_organize_photosfile_organizer_preview_organizationfile_organizer_read_filefile_organizer_scan_directoryfile_organizer_set_custom_rulesfile_organizer_smart_suggestfile_organizer_system_organizefile_organizer_undo_last_operationfile_organizer_unwatch_directoryfile_organizer_view_historyfile_organizer_watch_directory
Para parámetros y formas de retorno, consulta API.md.
Categorías de archivos
Categoría | Extensiones típicas |
Ejecutables |
|
Vídeos |
|
Documentos |
|
Imágenes |
|
Audio |
|
Archivos |
|
Código |
|
Ejemplos de flujos de trabajo
Limpiar una carpeta de Descargas
Escanea la carpeta y revisa la distribución de archivos y el uso de espacio.
Identifica duplicados y archivos obsoletos.
Previsualiza los movimientos y conflictos.
Confirma y luego organiza en carpetas por categoría.
Resultado: una carpeta ordenada, duplicados marcados y espacio recuperado.
Organizar un proyecto
El asistente escanea el proyecto, divide los archivos en Código, Recursos y Documentos, mantiene intacto el árbol src/ y mueve los archivos de configuración sueltos, los readmes y las capturas de pantalla a sus carpetas correspondientes.
Encontrar y manejar duplicados
El asistente calcula hashes de archivos, agrupa duplicados, puntúa cada copia según ubicación, calidad del nombre y antigüedad, y recomienda cuáles conservar y cuáles eliminar. Informa del espacio desperdiciado. Tú decides si eliminar.
Descubrir archivos grandes
Señala una carpeta y lista los archivos más grandes por tamaño, marca copias de seguridad antiguas que puedes archivar y señala duplicados grandes.
Organizar música
Lee las etiquetas ID3 y reconstruye la carpeta como Artista / Álbum / Título.mp3.
Before:
Downloads/
song1.mp3
track02.mp3
music_file.mp3
After:
Music/
Coldplay/
A Rush of Blood to the Head/
Clocks.mp3
The Scientist.mp3
Radiohead/
OK Computer/
Paranoid Android.mp3
Karma Police.mp3Organizar fotos
Lee la fecha de captura de los metadatos EXIF y ordena las fotos en carpetas AAAA / MM / DD.
Before:
Pictures/
IMG_001.jpg
photo123.png
DSC_4567.raw
After:
Pictures/
2023/
12/
25/
IMG_001.jpg
31/
photo123.png
2024/
01/
15/
DSC_4567.rawRevisión de seguridad de una carpeta
Extrae metadatos y firmas de contenido, luego señala metadatos sensibles, como coordenadas GPS EXIF en un PDF o identificadores personales en un currículum, y sugiere redacción o cuarentena.
Configurar organización automática
Registra un directorio con un horario cron:
{
"directory": "/Users/john/Downloads",
"schedule": "0 9 * * *",
"min_file_age_minutes": 5
}El servidor organiza la carpeta según ese horario. Añade más vigilancias para otros directorios.
Configuración de seguridad
El acceso está restringido a una lista blanca de directorios de usuario por defecto. Los directorios del sistema permanecen bloqueados.
Permitidos por defecto
El servidor habilita estas ubicaciones si existen en la máquina:
Plataforma | Directorios permitidos |
Windows | Escritorio, Documentos, Descargas, Imágenes, Vídeos, Música, OneDrive, Proyectos, Workspace |
macOS | Escritorio, Documentos, Descargas, Películas, Música, Imágenes, iCloud Drive, Proyectos |
Linux | Escritorio, Documentos, Descargas, Música, Imágenes, Vídeos, |
Siempre bloqueados
Estas rutas permanecen bloqueadas incluso si las añades a la configuración:
Windows:
C:\Windows, Archivos de Programa, AppData,$Recycle.BinmacOS:
/System,/Library,/Applications,/private,/usrLinux:
/etc,/usr,/var,/root,/sys,/procEn todas partes:
node_modules,.git,.vscode,.idea,dist,build
Configuración personalizada
Edita el archivo de configuración del usuario:
Windows:
%APPDATA%\file-organizer-mcp\config.jsonmacOS:
$HOME/Library/Application Support/file-organizer-mcp/config.jsonLinux:
$HOME/.config/file-organizer-mcp/config.json
Añade rutas a customAllowedDirectories:
{
"customAllowedDirectories": [
"C:\\Users\\Name\\My Special Folder",
"D:\\Backups"
]
}Puedes pegar una ruta de carpeta directamente desde la barra de direcciones de tu explorador de archivos.
Unidades externas y montajes de red
Las rutas fuera de tu directorio personal están bloqueadas a menos que optes por permitirlas. Para permitir un volumen externo como /Volumes/My Drive en macOS o /media/user/usb en Linux, establece allowExternalVolumes en true:
{
"allowExternalVolumes": true,
"customAllowedDirectories": [
"/Volumes/MyExternalDrive",
"/Volumes/Photography Backup"
]
}Las letras de unidad de Windows como D:\ funcionan sin esta marca.
Reinicia el cliente después de editar la configuración.
Estrategia de conflictos
{
"conflictStrategy": "rename"
}rename(por defecto) - Añade un sufijo al nuevo archivo, por ejemplofile (1).txt.skip- Mantiene el archivo existente y omite el nuevo.overwrite- Reemplaza el archivo existente, después de crear una copia de seguridad.
Horario de auto-organización heredado
Para un horario simple por horas, días o semanas:
{
"autoOrganize": {
"enabled": true,
"schedule": "daily"
}
}Para algo más granular, usa la herramienta file_organizer_watch_directory.
Defensas
Tipo de ataque | Protección |
Acceso no autorizado | Aplicación de lista blanca más lista negra |
Recorrido de rutas | Pipeline de validación de 8 capas |
Ataques de enlaces simbólicos | Resolución de ruta real |
DoS | Límites de recursos en número de archivos, profundidad y tamaño |
Solución de problemas
El servidor MCP no aparece
Comprueba que la ruta del archivo de configuración sea correcta.
Confirma que Node.js 18 o superior esté instalado:
node --version.Reinicia completamente el cliente.
Comprueba la ruta en el archivo de configuración del cliente.
Errores de permisos
Windows: ejecuta el cliente como Administrador.
macOS/Linux: comprueba los permisos de la carpeta con
ls -la.Confirma que el directorio de destino sea escribible.
Los archivos no se mueven
Asegúrate de que
dry_runno esté habilitado.Cierra programas que puedan estar bloqueando los archivos.
Comprueba que haya suficiente espacio en disco.
Lee el resumen de la operación para ver los mensajes de error.
Arquitectura
El servidor ejecuta un pipeline de examinar y enriquecer: un manejador de protocolo MCP pasa cada solicitud a través de un examen de seguridad (validación de rutas, detección de archivos sensibles, limitación de velocidad), luego enriquecimiento de metadatos (EXIF, ID3, propiedades de documentos), y luego la capa de servicios que realiza la operación. Todas las operaciones de archivos pasan por rutas validadas y admiten reversión.
Consulta ARCHITECTURE.md para ver el diagrama completo y las notas de diseño.
Documentación
API.md - Referencia completa de herramientas
ARCHITECTURE.md - Diseño y arquitectura
CONTRIBUTING.md - Guía de contribución
MIGRATION.md - Guía de actualización de v2 a v3
CHANGELOG.md - Historial de versiones
SECURITY.md - Modelo de seguridad y reporte
Contribución
Lee CONTRIBUTING.md, luego clona y compila:
git clone https://github.com/kridaydave/File-Organizer-MCP.git
cd File-Organizer-MCP
npm install
npm run build
npm testReporta errores y solicitudes de funciones en GitHub Issues. Para una vulnerabilidad de seguridad, envía un correo a technocratix902@gmail.com.
Licencia
MIT. Consulta LICENSE.
Available Tools
26 toolsfile_organizer_analyze_duplicatesAnalyze Duplicate Files with Smart RecommendationsCRead-onlyIdempotent
Finds duplicate files and suggests which to keep/delete based on location, name quality, and age.
Inputs: directory (required), response_format, auto_select_keep, recommendation_strategy.
file_organizer_batch_read_filesBatch Read Files for LLM ContextARead-onlyIdempotent
Reads contents of all files in a specified folder for LLM context. For text files (documents, code, notes), reads the actual content. For media files (audio, video, images), reads metadata instead of binary content. Provides a comprehensive summary of folder contents.
Inputs: directory (required), max_files, file_types, include_content, +4 more.
file_organizer_batch_renameBatch Rename FilesADestructive
Rename multiple files using rules (find/replace, case, add text, numbering). "dry_run" defaults to true for safety.
Inputs: rules (required), files, dry_run, directory, +1 more.
file_organizer_categorize_by_typeCategorize Files by TypeARead-onlyIdempotent
Categorize files by their type (Executables, Videos, Documents, etc.) and show statistics for each category. Enable use_content_analysis to detect file type mismatches and security threats.
Inputs: directory (required), include_subdirs, response_format, use_content_analysis.
file_organizer_delete_duplicatesDelete Duplicate FilesBDestructive
Permanently deletes specified duplicate files. DESTRUCTIVE. Verifies hash/size before deletion.
Inputs: files_to_delete (required), response_format, create_backup_manifest.
file_organizer_find_duplicate_filesFind Duplicate FilesBRead-onlyIdempotent
Find duplicate files in a directory based on their content (SHA-256 hash). Shows potential wasted space.
Inputs: directory (required), limit, offset, response_format.
file_organizer_find_largest_filesFind Largest FilesARead-onlyIdempotent
Find the largest files in a directory. Useful for identifying space-consuming files and cleanup opportunities.
Inputs: directory (required), top_n, include_subdirs, response_format.
file_organizer_get_categoriesGet Available File CategoriesARead-onlyIdempotent
Returns the list of categories used for file organization
Inputs: response_format.
file_organizer_inspect_metadataInspect File MetadataARead-onlyIdempotent
Inspects a file and returns comprehensive but privacy-safe metadata. For images, extracts EXIF data (date, camera, dimensions). For audio, extracts ID3 tags (artist, album, title). Excludes sensitive data like GPS coordinates.
Inputs: file (required), response_format.
file_organizer_list_filesList Files in DirectoryARead-onlyIdempotent
List all files in a directory with basic information. Returns file names and paths. Does not recurse into subdirectories.
Inputs: directory (required), limit, offset, response_format.
file_organizer_list_watchesList Watched DirectoriesARead-onlyIdempotent
List all directories currently being watched with their schedules.
Inputs: response_format.
file_organizer_organize_by_contentOrganize Documents by ContentADestructive
Organize files based on content analysis. strategy='topic' groups documents (PDF, DOCX, TXT, MD, RTF, ODT) into topic-based folders. strategy='project' groups files across all types (documents, code, images) into detected project folders using shared name tokens, content terms, and identifiers. Use dry_run=true to preview changes.
Inputs: source_dir (required), target_dir (required), dry_run, strategy, +3 more.
file_organizer_organize_filesOrganize FilesCDestructive
Automatically organize files into categorized folders. Enable use_content_analysis to detect file type mismatches and potential security threats. Use dry_run=true to preview changes.
Inputs: directory (required), dry_run, response_format, conflict_strategy, +1 more.
file_organizer_organize_musicOrganize Music FilesBDestructive
Organize music files into structured folders based on metadata (Artist/Album). Supports MP3, FLAC, OGG, WAV, M4A, AAC. Use dry_run=true to preview changes.
Inputs: source_dir (required), target_dir (required), dry_run, structure, +4 more.
file_organizer_organize_photosOrganize Photo FilesADestructive
Organize photos into date-based folders using EXIF metadata. Supports JPG, PNG, TIFF, HEIC, RAW formats. Can group by camera model and strip GPS data for privacy. Use dry_run=true to preview changes.
Inputs: source_dir (required), target_dir (required), dry_run, strip_gps, +5 more.
file_organizer_organize_smartSmart Organize FilesADestructive
Automatically organizes mixed files (music, photos, documents) using the appropriate strategy for each type. Music → Artist/Album structure. Photos → Date-based folders with optional GPS stripping. Documents → Topic-based folders. Use dry_run=true to preview changes.
Inputs: source_dir (required), target_dir (required), dry_run, recursive, +6 more.
file_organizer_preview_organizationPreview File Organization PlanARead-onlyIdempotent
Shows what would happen if files were organized, WITHOUT making any changes. Shows moves, conflicts, and skip reasons.
Inputs: directory (required), response_format, conflict_strategy, show_conflicts_only.
file_organizer_read_fileRead File ContentsARead-onlyIdempotent
Read file contents with security checks. Supports text, binary, and base64 encoding. Automatically detects file type and applies appropriate security validations. Sensitive files (passwords, keys, credentials) are automatically blocked.
Inputs: path (required), limit, offset, encoding, +3 more.
file_organizer_scan_directoryScan Directory for Detailed InfoBRead-onlyIdempotent
Scan directory and get detailed file information including size, dates, and extensions. Supports recursive scanning and security screening.
Inputs: directory (required), limit, offset, max_depth, +3 more.
file_organizer_set_custom_rulesSet Custom Organization RulesB
Customize how files are categorized. Rules persist for the current session.
Inputs: rules (required).
file_organizer_smart_suggestSmart SuggestCRead-onlyIdempotent
Analyze directory health and get actionable suggestions for organization
Inputs: directory (required), max_files, use_cache, sample_rate, +4 more.
file_organizer_system_organizeSystem OrganizeCDestructive
Organize files into OS-standard system directories (Music, Documents, Pictures, Videos)
Inputs: source_dir (required), dry_run, response_format, use_system_dirs, +5 more.
file_organizer_undo_last_operationUndo Last Organization OperationCDestructive
Reverses file moves and renames from a previous organization task.
Inputs: manifest_id, response_format.
file_organizer_unwatch_directoryUnwatch DirectoryBIdempotent
Remove a directory from the watch list.
Inputs: directory (required), response_format.
file_organizer_view_historyView HistoryARead-onlyIdempotent
View the history of file organization operations. Supports filtering by date range, operation type, status, and source. Use privacy_mode to control output detail level.
Inputs: limit, since, until, source, +4 more.
file_organizer_watch_directoryWatch DirectoryAIdempotent
Add a directory to the watch list with a cron-based schedule for automatic organization. When the user specifies a schedule in natural language (e.g., "every day at 10am"), convert it to a standard cron expression. Cron format: "minute hour day month weekday". Common conversions: "every day at 10am" → "0 10 * * ", "every 30 minutes" → "/30 * * * *", "every Monday at 9am" → "0 9 * * 1", "every hour" → "0 * * * *".
Inputs: schedule (required), directory (required), auto_organize, response_format, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 26 tools
There is significant overlap among tools, e.g., organize_files vs organize_smart vs organize_by_content vs system_organize, and find_duplicate_files vs analyze_duplicates. Descriptions help differentiate them, but an agent could easily pick the wrong one for a given task.
All 26 tools follow the consistent 'file_organizer_verb_noun' pattern, with clear verbs like list, scan, organize, read, watch. This is highly predictable and easy to navigate.
With 26 tools, the server is slightly above the 15-25 range. The broad feature set (organizing, watching, metadata, history) justifies many tools, but the count feels bloated, especially with overlapping functions that could be consolidated.
The tool set covers listing, scanning, categorization, duplicate detection, multiple organization strategies, preview, history, watching, renaming, and metadata inspection. Missing direct file deletion (except duplicates) and file editing, but those are outside the organizer's scope. Overall coverage is strong with minor gaps.
Maintenance
Related MCP Connectors
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Related MCP Servers
- AlicenseBqualityBmaintenanceComprehensive MCP server for filesystem operations, process management, interactive sessions, and async file search. Includes utilities for JSON repair, encoding fixes, duplicate detection, OCR, ZIP archives, and Markdown export.50205 npm6MIT
- AlicenseNot gradedqualityDmaintenanceA production-ready MCP server enabling Claude and other LLMs to perform intelligent file operations with minimal token usage.MIT
- AlicenseNot gradedqualityCmaintenanceLocal-first MCP server for safely searching, reading, summarizing, tagging, deduplicating, and organizing local files with scoped access, read-only defaults, and dry-run plans.19MIT
- AlicenseCqualityCmaintenanceA full-featured secure MCP server for local file system operations, with built-in image processing, OCR and media tools. Fully compliant with the official Model Context Protocol specification, offering standardized request/response schemas, large-file streaming I/O, multi-transport remote deployment, and comprehensive text search & replace functionality for LLM agent integration.2217 PyPIApache 2.0