Skip to main content
Glama
File Organizer MCP

File Organizer MCP

by kridaydave

File Organizer MCP Server

Versión 3.5.0 | Protocolo MCP 2024-11-05 | Node.js 18+

npm version npm downloads License Tests

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 read / write / rename

organize_files() ejecuta todo el movimiento atómicamente

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 --setup

El 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

npx file-organizer-mcp --setup

Uso ocasional o prueba

Global

npm install -g file-organizer-mcp

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. directory es obligatorio; include_subdirs activa la recursión.

  • file_organizer_read_file - Lee un archivo con validación de ruta de 8 capas. path es obligatorio; encoding puede 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_duplicates

  • file_organizer_batch_read_files

  • file_organizer_categorize_by_type

  • file_organizer_delete_duplicates

  • file_organizer_find_duplicate_files

  • file_organizer_find_largest_files

  • file_organizer_get_categories

  • file_organizer_inspect_metadata

  • file_organizer_list_files

  • file_organizer_list_watches

  • file_organizer_organize_by_content

  • file_organizer_organize_files

  • file_organizer_organize_music

  • file_organizer_organize_photos

  • file_organizer_preview_organization

  • file_organizer_read_file

  • file_organizer_scan_directory

  • file_organizer_set_custom_rules

  • file_organizer_smart_suggest

  • file_organizer_system_organize

  • file_organizer_undo_last_operation

  • file_organizer_unwatch_directory

  • file_organizer_view_history

  • file_organizer_watch_directory

Para parámetros y formas de retorno, consulta API.md.


Categorías de archivos

Categoría

Extensiones típicas

Ejecutables

.exe, .msi, .bat, .sh

Vídeos

.mp4, .avi, .mkv, .mov

Documentos

.pdf, .doc, .docx, .txt, .md

Imágenes

.jpg, .jpeg, .png, .gif, .webp

Audio

.mp3, .wav, .flac, .m4a

Archivos

.zip, .rar, .7z, .tar.gz

Código

.py, .js, .ts, .java, .go, .json


Ejemplos de flujos de trabajo

Limpiar una carpeta de Descargas

  1. Escanea la carpeta y revisa la distribución de archivos y el uso de espacio.

  2. Identifica duplicados y archivos obsoletos.

  3. Previsualiza los movimientos y conflictos.

  4. 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.mp3

Organizar 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.raw

Revisió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, ~/dev, ~/workspace

Siempre bloqueados

Estas rutas permanecen bloqueadas incluso si las añades a la configuración:

  • Windows: C:\Windows, Archivos de Programa, AppData, $Recycle.Bin

  • macOS: /System, /Library, /Applications, /private, /usr

  • Linux: /etc, /usr, /var, /root, /sys, /proc

  • En 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.json

  • macOS: $HOME/Library/Application Support/file-organizer-mcp/config.json

  • Linux: $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 ejemplo file (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

  1. Comprueba que la ruta del archivo de configuración sea correcta.

  2. Confirma que Node.js 18 o superior esté instalado: node --version.

  3. Reinicia completamente el cliente.

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

  1. Asegúrate de que dry_run no esté habilitado.

  2. Cierra programas que puedan estar bloqueando los archivos.

  3. Comprueba que haya suficiente espacio en disco.

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


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 test

Reporta 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 tools
file_organizer_analyze_duplicatesAnalyze Duplicate Files with Smart RecommendationsC
Read-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 ContextA
Read-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 FilesA
Destructive

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 TypeA
Read-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 FilesB
Destructive

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 FilesB
Read-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 FilesA
Read-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 CategoriesA
Read-onlyIdempotent

Returns the list of categories used for file organization

Inputs: response_format.

file_organizer_inspect_metadataInspect File MetadataA
Read-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 DirectoryA
Read-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 DirectoriesA
Read-onlyIdempotent

List all directories currently being watched with their schedules.

Inputs: response_format.

file_organizer_organize_by_contentOrganize Documents by ContentA
Destructive

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 FilesC
Destructive

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 FilesB
Destructive

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 FilesA
Destructive

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 FilesA
Destructive

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 PlanA
Read-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 ContentsA
Read-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 InfoB
Read-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 SuggestC
Read-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 OrganizeC
Destructive

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 OperationC
Destructive

Reverses file moves and renames from a previous organization task.

Inputs: manifest_id, response_format.

file_organizer_unwatch_directoryUnwatch DirectoryB
Idempotent

Remove a directory from the watch list.

Inputs: directory (required), response_format.

file_organizer_view_historyView HistoryA
Read-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 DirectoryA
Idempotent

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

    B3.4/5.0

    Scored across 26 tools

    Disambiguation3/5

    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.

    Naming Consistency5/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityActive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Comprehensive 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.
      50
      205 npm
      6
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Local-first MCP server for safely searching, reading, summarizing, tagging, deduplicating, and organizing local files with scoped access, read-only defaults, and dry-run plans.
      19
      MIT
    • A
      license
      C
      quality
      C
      maintenance
      A 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.
      22
      17 PyPI
      Apache 2.0