File Organizer MCP
File Organizer MCP Server
Version 3.5.0 | MCP-Protokoll 2024-11-05 | Node.js 18+
Ein Model Context Protocol (MCP)-Server, der Dateien organisiert. Er gibt einem Claude-artigen Assistenten eine einzige atomare Operation zum Kategorisieren, Sortieren, Deduplizieren und Umbenennen von Dateien, anstatt ihn Dutzende primitive read-, write- und rename-Aufrufe verketten zu lassen.
Warum
Ein Dateisystem-MCP-Server, der nur auf read, write, make und delete aufbaut, zwingt einen Assistenten, jede Verschiebung und Umbenennung als separaten Schritt zu planen. Jeder Schritt kostet Tokens, und mehr Schritte bedeuten mehr Chancen, den Pfad falsch zu treffen.
File Organizer MCP ersetzt diese Ketten durch einen einzigen Aufruf:
Primitive Vorgehensweise | File Organizer MCP |
Viele |
|
Dutzende Denkschritte | Ein Denkschritt |
Hoher Token-Verbrauch | Minimaler Token-Verbrauch |
Leicht zu beschädigen bei Teilfehlern | Rollback-sichere Operationen |
Related MCP server: MCP Filesystem Agent v3
Schnellstart
Einrichtung mit einem Befehl
npx file-organizer-mcp --setupDer Assistent erkennt installierte KI-Clients (Claude Desktop, Cursor, Windsurf, Cline und andere), konfiguriert sie und führt Sie durch die Ordnerauswahl und Einstellungen.
Anforderungen
Node.js 18 oder neuer.
Nach der Einrichtung
Sie können den Assistenten zum Beispiel bitten:
„Organisiere meinen Downloads-Ordner"
„Finde doppelte Dateien in meinen Dokumenten"
„Zeig mir meine größten Dateien"
Installationsmethoden
Methode | Befehl | Anwendungsfall |
npx |
| Gelegentliche Nutzung oder Testlauf |
Global |
| Regelmäßige Nutzung, schnellerer Start |
Funktionen
Kategorisierung in 12 oder mehr Dateitypen.
Cron-basierte automatische Organisation und Verzeichnisüberwachung.
Duplikaterkennung durch SHA-256-Inhalts-Hash.
Metadaten-Extraktion: EXIF für Fotos, ID3 für Audio, Themenextraktion für Dokumente.
Intelligente Organisation, die die richtige Strategie pro Dateityp wählt.
Trockenlauf-Vorschau, atomare Verschiebungen und Rollback.
Schutz vor Pfad-Traversal, TOCTOU-Minderung und Metadaten-Bereinigung.
Windows, macOS und Linux.
Werkzeuge
Kernwerkzeuge
file_organizer_scan_directory– Listet ein Verzeichnis mit detaillierten Dateiinformationen auf.directoryist erforderlich;include_subdirsschaltet die Rekursion um.file_organizer_read_file– Liest eine Datei mit 8-stufiger Pfadvalidierung.pathist erforderlich;encodingist utf-8, base64 oder binary.file_organizer_organize_smart– Verarbeitet Musik, Fotos und Dokumente in einem Durchgang und wählt die beste Strategie pro Datei.file_organizer_batch_rename– Benennt viele Dateien nach Muster, Regex oder Nummerierung um.file_organizer_undo_last_operation– Macht die letzte Organisation rückgängig.
Vollständige Werkzeugliste
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
Für Parameter und Rückgabetypen siehe API.md.
Dateikategorien
Kategorie | Typische Erweiterungen |
Ausführbare Dateien |
|
Videos |
|
Dokumente |
|
Bilder |
|
Audio |
|
Archive |
|
Code |
|
Beispiel-Workflows
Downloads-Ordner aufräumen
Scannen Sie den Ordner und prüfen Sie die Dateiverteilung und den Speicherplatz.
Identifizieren Sie Duplikate und veraltete Dateien.
Vorschau der Verschiebungen und Konflikte.
Bestätigen und dann in Kategorieordner organisieren.
Ergebnis: ein sortierter Ordner, Duplikate markiert und Speicherplatz freigegeben.
Ein Projekt organisieren
Der Assistent scannt das Projekt, teilt die Dateien in Code, Assets und Docs auf, hält den src/-Baum intakt und verschiebt lose Konfigurationsdateien, Readmes und Screenshots in die richtigen Ordner.
Duplikate finden und behandeln
Der Assistent hasht Dateien, gruppiert Duplikate, bewertet jede Kopie nach Speicherort, Namensqualität und Alter und empfiehlt, welche behalten und welche gelöscht werden sollen. Er meldet den verschwendeten Speicherplatz. Sie entscheiden, ob gelöscht wird.
Große Dateien entdecken
Zeigen Sie auf einen Ordner und er listet die größten Dateien nach Größe auf, markiert alte Backups, die Sie archivieren können, und weist auf große Duplikate hin.
Musik organisieren
Er liest ID3-Tags und baut den Ordner als Künstler / Album / Titel.mp3 neu auf.
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.mp3Fotos organisieren
Er liest das Aufnahmedatum aus EXIF und sortiert Fotos in YYYY / MM / DD-Ordner.
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.rawOrdner auf Sicherheit prüfen
Er extrahiert Metadaten und Inhalts-Signaturen und markiert dann sensible Metadaten, wie EXIF-GPS-Koordinaten in einer PDF oder persönliche Identifikatoren in einem Lebenslauf, und schlägt eine Bereinigung oder Quarantäne vor.
Automatische Organisation einrichten
Registrieren Sie ein Verzeichnis mit einem Cron-Zeitplan:
{
"directory": "/Users/john/Downloads",
"schedule": "0 9 * * *",
"min_file_age_minutes": 5
}Der Server organisiert den Ordner nach diesem Zeitplan. Fügen Sie weitere Überwachungen für andere Verzeichnisse hinzu.
Sicherheitskonfiguration
Der Zugriff ist standardmäßig auf eine Whitelist von Benutzerverzeichnissen beschränkt. Systemverzeichnisse bleiben blockiert.
Standardmäßig erlaubt
Der Server aktiviert diese Speicherorte, wenn sie auf dem Rechner vorhanden sind:
Plattform | Erlaubte Verzeichnisse |
Windows | Desktop, Dokumente, Downloads, Bilder, Videos, Musik, OneDrive, Projekte, Arbeitsbereich |
macOS | Desktop, Dokumente, Downloads, Filme, Musik, Bilder, iCloud Drive, Projekte |
Linux | Desktop, Dokumente, Downloads, Musik, Bilder, Videos, |
Immer blockiert
Diese Pfade bleiben blockiert, auch wenn Sie sie zur Konfiguration hinzufügen:
Windows:
C:\Windows, Program Files, AppData,$Recycle.BinmacOS:
/System,/Library,/Applications,/private,/usrLinux:
/etc,/usr,/var,/root,/sys,/procÜberall:
node_modules,.git,.vscode,.idea,dist,build
Benutzerdefinierte Konfiguration
Bearbeiten Sie die Benutzerkonfigurationsdatei:
Windows:
%APPDATA%\file-organizer-mcp\config.jsonmacOS:
$HOME/Library/Application Support/file-organizer-mcp/config.jsonLinux:
$HOME/.config/file-organizer-mcp/config.json
Fügen Sie Pfade zu customAllowedDirectories hinzu:
{
"customAllowedDirectories": [
"C:\\Users\\Name\\My Special Folder",
"D:\\Backups"
]
}Sie können einen Ordnerpfad direkt aus der Adressleiste Ihres Datei-Explorers einfügen.
Externe Laufwerke und Netzwerk-Mounts
Pfade außerhalb Ihres Home-Verzeichnisses sind blockiert, es sei denn, Sie stimmen zu. Um ein externes Volume wie /Volumes/My Drive auf macOS oder /media/user/usb auf Linux zu erlauben, setzen Sie allowExternalVolumes auf true:
{
"allowExternalVolumes": true,
"customAllowedDirectories": [
"/Volumes/MyExternalDrive",
"/Volumes/Photography Backup"
]
}Windows-Laufwerksbuchstaben wie D:\ funktionieren ohne dieses Flag.
Starten Sie den Client nach der Bearbeitung der Konfiguration neu.
Konfliktstrategie
{
"conflictStrategy": "rename"
}rename(Standard) – Fügen Sie dem neuen Datei ein Suffix hinzu, z. B.Datei (1).txt.skip– Behalten Sie die vorhandene Datei und überspringen Sie die neue.overwrite– Ersetzen Sie die vorhandene Datei, nachdem Sie ein Backup geschrieben haben.
Legacy-Zeitplan für automatische Organisation
Für einen einfachen stündlichen, täglichen oder wöchentlichen Zeitplan:
{
"autoOrganize": {
"enabled": true,
"schedule": "daily"
}
}Für etwas Granulareres verwenden Sie das Werkzeug file_organizer_watch_directory.
Schutzmaßnahmen
Angriffstyp | Schutz |
Unbefugter Zugriff | Whitelist plus Blacklist-Durchsetzung |
Pfad-Traversal | 8-stufige Validierungspipeline |
Symlink-Angriffe | Auflösung des echten Pfads |
DoS | Ressourcenlimits für Dateianzahl, Tiefe und Größe |
Fehlerbehebung
Der MCP-Server erscheint nicht
Prüfen Sie, ob der Konfigurationsdateipfad korrekt ist.
Bestätigen Sie Node.js 18 oder neuer:
node --version.Starten Sie den Client vollständig neu.
Prüfen Sie den Pfad in der Client-Konfigurationsdatei.
Berechtigungsfehler
Windows: Führen Sie den Client als Administrator aus.
macOS/Linux: Prüfen Sie die Ordnerberechtigungen mit
ls -la.Bestätigen Sie, dass das Zielverzeichnis beschreibbar ist.
Dateien werden nicht verschoben
Stellen Sie sicher, dass
dry_runnicht aktiviert ist.Schließen Sie Programme, die die Dateien möglicherweise sperren.
Prüfen Sie, ob genügend Speicherplatz vorhanden ist.
Lesen Sie die Operationszusammenfassung auf Fehlermeldungen.
Architektur
Der Server führt eine Prüf- und Anreicherungs-Pipeline aus: Ein MCP-Protokoll-Handler leitet jede Anfrage durch die Sicherheitsprüfung (Pfadvalidierung, Erkennung sensibler Dateien, Ratenbegrenzung), dann durch die Metadaten-Anreicherung (EXIF, ID3, Dokumenteigenschaften), dann durch die Service-Schicht, die die Operation ausführt. Alle Dateioperationen laufen über validierte Pfade und unterstützen Rollback.
Siehe ARCHITECTURE.md für das vollständige Diagramm und die Design-Notizen.
Dokumentation
API.md – Vollständige Werkzeugreferenz
ARCHITECTURE.md – Design und Architektur
CONTRIBUTING.md – Beitragsrichtlinien
MIGRATION.md – Upgrade-Anleitung von v2 auf v3
CHANGELOG.md – Versionsverlauf
SECURITY.md – Sicherheitsmodell und Meldung
Mitwirken
Lesen Sie CONTRIBUTING.md, klonen Sie dann und bauen Sie:
git clone https://github.com/kridaydave/File-Organizer-MCP.git
cd File-Organizer-MCP
npm install
npm run build
npm testMelden Sie Fehler und Funktionswünsche auf GitHub Issues. Für eine Sicherheitslücke senden Sie eine E-Mail an technocratix902@gmail.com.
Lizenz
MIT. Siehe 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