Skip to main content
Glama
File Organizer MCP

File Organizer MCP

by kridaydave

File Organizer MCP Server

Версия 3.5.0 | MCP protocol 2024-11-05 | Node.js 18+

npm version npm downloads License Tests

Сервер Model Context Protocol (MCP), который организует файлы. Он предоставляет ассистенту в стиле Claude одну атомарную операцию для категоризации, сортировки, дедупликации и переименования файлов, вместо того чтобы заставлять его выполнять цепочки из десятков примитивных вызовов read, write и rename.


Зачем

Файловый MCP-сервер, построенный только на read, write, make и delete, вынуждает ассистента планировать каждое перемещение и переименование как отдельный шаг. Каждый шаг стоит токенов, а чем больше шагов, тем больше шансов ошибиться в пути.

File Organizer MCP заменяет эти цепочки одним вызовом:

Примитивный подход

File Organizer MCP

Много вызовов read / write / rename

organize_files() выполняет всё перемещение атомарно

Десятки шагов рассуждений

Один шаг рассуждений

Высокий расход токенов

Минимальный расход токенов

Легко повредить при частичном сбое

Операции с безопасным откатом


Related MCP server: MCP Filesystem Agent v3

Быстрый старт

Установка одной командой

npx file-organizer-mcp --setup

Мастер обнаруживает установленные AI-клиенты (Claude Desktop, Cursor, Windsurf, Cline и другие), настраивает их и проводит вас через выбор папок и предпочтений.

Требования

Node.js 18 или новее.

После установки

Вы можете попросить ассистента, например:

  • «Организуй мою папку Downloads»

  • «Найди дубликаты файлов в моих документах»

  • «Покажи мои самые большие файлы»

Способы установки

Метод

Команда

Сценарий использования

npx

npx file-organizer-mcp --setup

Эпизодическое использование или пробная версия

Глобально

npm install -g file-organizer-mcp

Регулярное использование, более быстрый запуск


Возможности

  • Категоризация по 12 и более типам файлов.

  • Автоматическая организация по расписанию (cron) и режим наблюдения за каталогами.

  • Обнаружение дубликатов по SHA-256 хешу содержимого.

  • Извлечение метаданных: EXIF для фотографий, ID3 для аудио, извлечение темы для документов.

  • Умная организация, которая выбирает правильную стратегию для каждого типа файлов.

  • Предварительный просмотр (dry-run), атомарные перемещения и откат.

  • Защита от path traversal, смягчение TOCTOU и очистка метаданных.

  • Windows, macOS и Linux.


Инструменты

Основные инструменты

  • file_organizer_scan_directory — Список каталога с подробной информацией о файлах. directory обязателен; include_subdirs включает рекурсию.

  • file_organizer_read_file — Чтение файла с 8-уровневой проверкой пути. path обязателен; encoding — utf-8, base64 или binary.

  • file_organizer_organize_smart — Обработка музыки, фотографий и документов за один проход, выбор лучшей стратегии для каждого файла.

  • file_organizer_batch_rename — Переименование множества файлов по шаблону, регулярному выражению или нумерации.

  • file_organizer_undo_last_operation — Отмена последней операции организации.

Полный список инструментов

  • 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

Для параметров и возвращаемых значений см. API.md.


Категории файлов

Категория

Типичные расширения

Исполняемые

.exe, .msi, .bat, .sh

Видео

.mp4, .avi, .mkv, .mov

Документы

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

Изображения

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

Аудио

.mp3, .wav, .flac, .m4a

Архивы

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

Код

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


Примеры рабочих процессов

Очистка папки Downloads

  1. Просканируйте папку и просмотрите распределение файлов и использование места.

  2. Определите дубликаты и устаревшие файлы.

  3. Предварительно просмотрите перемещения и конфликты.

  4. Подтвердите, затем организуйте в папки по категориям.

Результат: отсортированная папка, отмеченные дубликаты и освобождённое место.

Организация проекта

Ассистент сканирует проект, разделяет файлы на Код, Ресурсы и Документы, сохраняет структуру src/ нетронутой и перемещает свободные конфигурационные файлы, readme и скриншоты в соответствующие папки.

Поиск и обработка дубликатов

Ассистент хеширует файлы, группирует дубликаты, оценивает каждую копию по расположению, качеству имени и возрасту, и рекомендует, какие оставить, а какие удалить. Он сообщает о потраченном впустую месте. Вы решаете, удалять ли.

Поиск больших файлов

Укажите папку, и он перечислит самые большие файлы по размеру, отметит старые резервные копии, которые можно заархивировать, и заметит крупные дубликаты.

Организация музыки

Он читает ID3-теги и перестраивает папку в Исполнитель / Альбом / Название.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

Организация фотографий

Он читает дату съёмки из EXIF и сортирует фотографии в папки ГГГГ / ММ / ДД.

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

Проверка папки на безопасность

Он извлекает метаданные и сигнатуры содержимого, затем отмечает чувствительные метаданные, такие как GPS-координаты EXIF в PDF или личные идентификаторы в резюме, и предлагает редактирование или карантин.

Настройка автоматической организации

Зарегистрируйте каталог с расписанием cron:

{
  "directory": "/Users/john/Downloads",
  "schedule": "0 9 * * *",
  "min_file_age_minutes": 5
}

Сервер организует папку по этому расписанию. Добавьте больше наблюдений для других каталогов.


Конфигурация безопасности

Доступ по умолчанию ограничен белым списком пользовательских каталогов. Системные каталоги остаются заблокированными.

Разрешено по умолчанию

Сервер включает эти расположения, если они существуют на машине:

Платформа

Разрешённые каталоги

Windows

Desktop, Documents, Downloads, Pictures, Videos, Music, OneDrive, Projects, Workspace

macOS

Desktop, Documents, Downloads, Movies, Music, Pictures, iCloud Drive, Projects

Linux

Desktop, Documents, Downloads, Music, Pictures, Videos, ~/dev, ~/workspace

Всегда заблокировано

Эти пути остаются заблокированными, даже если вы добавите их в конфигурацию:

  • Windows: C:\Windows, Program Files, AppData, $Recycle.Bin

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

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

  • Везде: node_modules, .git, .vscode, .idea, dist, build

Пользовательская конфигурация

Отредактируйте пользовательский файл конфигурации:

  • 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

Добавьте пути в customAllowedDirectories:

{
  "customAllowedDirectories": [
    "C:\\Users\\Name\\My Special Folder",
    "D:\\Backups"
  ]
}

Вы можете вставить путь к папке прямо из адресной строки вашего файлового менеджера.

Внешние диски и сетевые монтирования

Пути за пределами вашего домашнего каталога заблокированы, если вы не согласитесь. Чтобы разрешить внешний том, например /Volumes/My Drive на macOS или /media/user/usb на Linux, установите allowExternalVolumes в true:

{
  "allowExternalVolumes": true,
  "customAllowedDirectories": [
    "/Volumes/MyExternalDrive",
    "/Volumes/Photography Backup"
  ]
}

Буквы дисков Windows, такие как D:\, работают без этого флага.

Перезапустите клиент после редактирования конфигурации.

Стратегия разрешения конфликтов

{
  "conflictStrategy": "rename"
}
  • rename (по умолчанию) — Добавляет суффикс к новому файлу, например file (1).txt.

  • skip — Сохраняет существующий файл и пропускает новый.

  • overwrite — Заменяет существующий файл, предварительно создав резервную копию.

Устаревшее расписание автоматической организации

Для простого расписания — ежечасно, ежедневно или еженедельно:

{
  "autoOrganize": {
    "enabled": true,
    "schedule": "daily"
  }
}

Для более детального расписания используйте инструмент file_organizer_watch_directory.

Защита

Тип атаки

Защита

Несанкционированный доступ

Белый список плюс чёрный список

Path traversal

8-уровневый конвейер проверки

Атаки через симлинки

Разрешение реального пути

DoS

Ограничения ресурсов по количеству файлов, глубине и размеру


Устранение неполадок

Сервер MCP не появляется

  1. Проверьте, что путь к файлу конфигурации правильный.

  2. Убедитесь, что Node.js 18 или новее: node --version.

  3. Полностью перезапустите клиент.

  4. Проверьте путь в файле конфигурации клиента.

Ошибки прав доступа

  • Windows: запустите клиент от имени администратора.

  • macOS/Linux: проверьте права на папки с помощью ls -la.

  • Убедитесь, что целевой каталог доступен для записи.

Файлы не перемещаются

  1. Убедитесь, что dry_run не включён.

  2. Закройте программы, которые могут блокировать файлы.

  3. Проверьте, достаточно ли места на диске.

  4. Прочитайте сводку операции для сообщений об ошибках.


Архитектура

Сервер выполняет конвейер «проверка-обогащение»: обработчик протокола MCP пропускает каждый запрос через проверку безопасности (проверка пути, обнаружение чувствительных файлов, ограничение скорости), затем обогащение метаданными (EXIF, ID3, свойства документов), затем сервисный уровень, выполняющий операцию. Все файловые операции проходят через проверенные пути и поддерживают откат.

См. ARCHITECTURE.md для полной диаграммы и заметок по дизайну.


Документация

  • API.md — Полный справочник по инструментам

  • ARCHITECTURE.md — Дизайн и архитектура

  • CONTRIBUTING.md — Рекомендации по вкладу

  • MIGRATION.md — Руководство по обновлению с v2 на v3

  • CHANGELOG.md — История версий

  • SECURITY.md — Модель безопасности и отчёты


Вклад в проект

Прочитайте CONTRIBUTING.md, затем клонируйте и соберите:

git clone https://github.com/kridaydave/File-Organizer-MCP.git
cd File-Organizer-MCP
npm install
npm run build
npm test

Сообщайте об ошибках и запросах функций на GitHub Issues. Для уязвимостей безопасности напишите на technocratix902@gmail.com.

Лицензия

MIT. См. 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