File Organizer MCP
File Organizer MCP is a stateless MCP server for atomic, rollback-safe file organization and analysis.
Scan and list directories with detailed file info.
Categorize files by type, content, date, project, music metadata, or photo EXIF.
Find largest files, duplicates, empty folders, broken symlinks, old files, and disk usage by category.
Organize, smart-organize, or system-organize files into structured folders with dry-run preview.
Batch rename files with collision checks and undo/rollback support.
Read files, batch-read for LLM context, and extract privacy-safe metadata.
Quarantine suspicious files reversibly and restore them later.
Validate organization plans for collisions, blocked paths, and cross-device moves.
View, search, export, and undo operation history; export config/reports.
Schedule automatic organization via cron/watch process and OS timers.
Enforce path whitelists/blacklists, sensitive-file blocking, and resource limits.
File Organizer MCP Server
Version 5.0.0 | MCP protocol 2026-07-28, stateless | Node.js 20+
A Model Context Protocol server that organizes files. It gives a Claude-style assistant a single atomic operation to categorize, sort, dedupe, and rename files, instead of making it chain dozens of primitive read, write, and rename calls.
Why
A filesystem MCP server built only on read, write, make, and delete forces an assistant to plan every move and rename as a separate step. Each step costs tokens, and more steps means more chances to get the path wrong.
File Organizer MCP replaces those chains with one call:
Primitive approach | File Organizer MCP |
Many |
|
Dozens of reasoning steps | One reasoning step |
High token use | Minimal token use |
Easy to corrupt on partial failure | Rollback-safe operations |
Related MCP server: MCP Filesystem Agent v3
Quick start
One-command setup
npx file-organizer-mcp --setupThe wizard detects installed AI clients (Claude Desktop, Cursor, Windsurf, Cline, and others), configures them, and walks you through folder selection and preferences.
Requirements
Node.js 20 or newer.
After setup
You can ask the assistant things like:
"Organize my Downloads folder"
"Find duplicate files in my Documents"
"Show me my largest files"
"Which categories take up the most space in my Downloads?"
Install methods
Method | Command | Use case |
npx |
| Occasional use or a trial |
Global |
| Regular use, faster startup |
Features
Categorization into 12 or more file types.
Cron-based automatic organization and directory watch mode.
Duplicate detection by SHA-256 content hash.
Disk usage per category: which file types hold the space, in bytes and as a share.
Metadata extraction: EXIF for photos, ID3 for audio.
Smart organization that picks the right strategy per file type.
Date sorting into
YYYY/MMfolders from EXIF date taken (photos) or file mtime, reporting which date each file used.Dry-run preview, atomic moves, and rollback.
Plan validation before you organize: name collisions, occupied destinations, cross-device moves, and files the sensitive-file gate blocks.
Path traversal protection, TOCTOU mitigation.
Windows, macOS, and Linux.
Tools
Core tools
file_organizer_scan_directory- List a directory with detailed file info.directoryis required;include_subdirstoggles recursion.file_organizer_read_file- Read a file through the validated path pipeline.pathis required;encodingis utf-8, base64, or binary.file_organizer_batch_rename- Rename many files by pattern, regex, or numbering. Checks the whole plan for name collisions first: if a real run would put two files on one name, or overwrite a name a different file already holds, the batch is rejected before anything moves and the conflicts come back as structured data.file_organizer_undo_last_operation- Reverse the most recent organization, or any pass you name by the manifest id it returned andfile_organizer_view_historylists. Passcascade: trueto walk back through every pass made after that one, newest first. An older pass whose files a newer pass also touched is refused unless you ask for the cascade.file_organizer_quarantine_files- Set flagged files aside for review, reversibly. See below.file_organizer_restore_quarantine- Put quarantined files back where they came from.file_organizer_search_history- Filter the history by path glob (path_glob), date range (from/to), or operation type. Every filter is optional and they combine, so a long history stays queryable instead of one flat list.file_organizer_export_report- Write a health report for a directory in one call: totals, space per category, duplicate groups, largest files. Passoutput_pathto leave a file behind, or leave it out and nothing is written. See below.
Full tool list (42 tools)
file_organizer_analyze_duplicatesfile_organizer_batch_read_filesfile_organizer_batch_renamefile_organizer_categorize_by_typefile_organizer_delete_duplicatesfile_organizer_disk_usage_by_categoryfile_organizer_doctorfile_organizer_export_configfile_organizer_export_reportfile_organizer_find_broken_symlinksfile_organizer_find_duplicate_filesfile_organizer_find_empty_directoriesfile_organizer_find_largest_filesfile_organizer_find_old_filesfile_organizer_get_categoriesfile_organizer_inspect_metadatafile_organizer_list_filesfile_organizer_list_watchesfile_organizer_organize_by_datefile_organizer_organize_by_projectfile_organizer_organize_filesfile_organizer_organize_musicfile_organizer_organize_photosfile_organizer_organizer_digestfile_organizer_preview_delete_duplicatesfile_organizer_preview_organizationfile_organizer_quarantine_filesfile_organizer_read_filefile_organizer_restore_quarantinefile_organizer_scan_directoryfile_organizer_search_historyfile_organizer_sensitive_scanfile_organizer_set_custom_rulesfile_organizer_smart_suggestfile_organizer_system_organizefile_organizer_undo_last_operationfile_organizer_unwatch_directoryfile_organizer_validate_organization_planfile_organizer_verify_integrityfile_organizer_view_historyfile_organizer_watch_directoryfile_organizer_watch_status
For parameters and return shapes, see API.md.
Quarantine: set files aside without losing them
Scanning flags a suspicious file. Deleting it is not reversible. Quarantine is the middle option: the file is moved into a hidden quarantine directory inside the directory you named, and it stays readable on disk.
file_organizer_quarantine_files({
directory: "~/Downloads",
files: ["~/Downloads/invoice.exe"],
reason: "flags as executable content",
})Reversibility is the whole point, so it comes back two ways:
file_organizer_undo_last_operation. The existing undo path reverses a quarantine. writes the same rollback manifest the organizer writes, so undo is the same call you already use.file_organizer_restore_quarantine. It reads that manifest and puts every file back at the exact path it was taken from. The restore writes a manifest of its own, so the restore is reversible too.
What to know before you move something:
Dry run by default. A bare call lists what would be quarantined and moves nothing. Pass
dry_run: falseto apply it.Nothing is deleted. No file is removed from disk by quarantine. Only its location changes.
The quarantine directory is derived, not hardcoded. By default it is
.file-organizer-quarantineinside thedirectoryyou passed, which means it inherits that directory's access grant. Setquarantine_dirto move it elsewhere. It goes through the same path validation as any other directory, so it cannot be pointed outside your allowed directories.Same names do not collide. Two files called
notes.txtbecomenotes.txtandnotes_1.txt. Neither overwrites the other, and a restore puts each back at its own original path.One batch at a time. Every listed file must live inside
directory. If any path is outside it, nothing moves.Paths in the result are absolute, like
organize_files. They are canonicalised, so they differ in spelling by platform. Windows expands 8.3 short names (RUNNER~1becomesrunneradmin) and macOS rewrites/varto/private/var. Compare basenames, or normalise both sides, instead of comparing raw path strings.
Scheduled organization (separate process)
The stdio MCP server stays stateless. Cron-based watching runs as its own process:
file-organizer-watch add ~/Downloads "0 10 * * *" # daily at 10am
file-organizer-watch list
file-organizer-watch # start the daemonWatches are stored in the shared user config, so add/remove work even
while the daemon is running (restart it to pick up changes).
An OS timer is the primary path. Point cron, a systemd timer, or Task
Scheduler at once (below) and the machine's own scheduler owns the schedule:
it survives reboots, it is visible in crontab -l, and it needs no process of
ours running.
# crontab -e: daily at 10am, labelled scheduled so history can filter on it
0 10 * * * file-organizer-watch once ~/Downloads --apply --source scheduledThe daemon is the fallback for a machine with no timer to point at. Both run the
same pass over the same watch config, so a watched directory behaves the same
way either way: same history row, same rollback manifest id, and the same
per-directory limits from watch add (the age filter and the file cap). The
daemon adds one thing a cron line does not have, which is catchup: on startup it
reads scheduler-state.json and runs a schedule that was missed while the
machine was off.
Single pass from an OS timer
once runs one organization pass and exits, holding no watcher, no timer, and
no open handle. That is the mode cron, launchd, a systemd timer, or Task
Scheduler drives:
file-organizer-watch once ~/Downloads # dry run, writes nothing
file-organizer-watch once ~/Downloads --apply # move, then exit
file-organizer-watch once . --apply --recursive --jsonExit codes
Code | Meaning |
| Pass finished, moved nothing: empty dir or dry run |
| Failed: bad flags, refused path, per-file errors, or abort |
| Pass finished clean and moved at least one file |
1 wins over 2 even when files moved, so a partial pass never looks like
success.
--json
--json prints exactly one JSON object on stdout and nothing else. Logs,
usage, and failure text go to stderr, so stdout stays parseable whether the
run succeeded or not.
{
"ok": true,
"exitCode": 2,
"directory": "/home/you/Downloads",
"dryRun": false,
"scanned": 12,
"planned": 8,
"moved": 8,
"skipped": 4,
"historyLogged": true,
"aborted": false,
"errors": []
}Every key is always present, including on failure. A refused path reports the
same shape with ok false, exitCode 1, and the reason in errors. ok is
true for exit codes 0 and 2. historyLogged: false on an applied pass means
no history row was written for the moves: nothing names that pass in history
and there is no id to undo it by, though the manifest may still be on disk.
When it is true, the row carries the rollback manifest id whenever the pass
managed to write one, so file_organizer_undo_last_operation can reverse the
pass file by file. A pass whose manifest write failed has a row with no id:
the pass is in history, but it cannot be undone by handle.
On a pass that ran, directory is the resolved path, not the argument
verbatim. The same convention every tool uses (file_organizer_organize_files
reports the directory its path validator approved). It is the path the gate
checked and the pass scanned, so symlinks are already followed and ~ is
expanded. The two forms differ on macOS (/var/folders/... →
/private/var/folders/...) and on Windows (an 8.3 short name like RUNNER~1
expands to the long name), so a caller must not string-compare it against what
it passed in.
The one exception is a failure that never reached a scan. A path the gate
refused, or a thrown error. There is no approved path to report, so directory
carries the original argument exactly as typed. Key your reports on exitCode
and errors, not on directory.
When scripting a pipeline, keep the CLI's exit code. Without pipefail the
pipeline reports jq's status, and a pass that moved files and then failed
would look like success:
set -o pipefail
# alert only when files moved AND the pass was clean.
# .ok rejects a partial pass that moved files but then failed.
file-organizer-watch once ~/Downloads --apply --json \
| jq -e '.ok and (.moved > 0)' >/dev/null && echo "organized"For a read-only sweep, scan plus preview_organization on a timer, no moves.
see examples/scheduling. It has ready-to-copy
recipes for three surfaces:
Surface | Trigger | Config |
Claude Desktop | headless | |
Codex |
| |
cron / systemd |
|
File categories
Category | Typical extensions |
Executables |
|
Videos |
|
Documents |
|
Images |
|
Audio |
|
Archives |
|
Code |
|
Example workflows
Clean up a Downloads folder
Scan the folder and review the file distribution and space use.
Identify duplicates and stale files.
Preview the moves and conflicts.
Confirm, then organize into category folders.
Result: a sorted folder, duplicates flagged, and reclaimed space.
Organize a project
The assistant scans the project, splits files into Code, Assets, and Docs, keeps the src/ tree intact, and moves loose config files, readmes, and screenshots into their proper folders.
Find and handle duplicates
The assistant hashes files, groups duplicates, scores each copy by location, name quality, and age, and recommends which to keep and which to delete. It reports the wasted space. You decide whether to delete.
Discover large files
Point it at a folder and it lists the largest files by size, flags old backups you can archive, and notes any large duplicates.
Organize music
It reads ID3 tags and rebuilds the folder as Artist / Album / Title.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.mp3Organize photos
It reads the capture date from EXIF and sorts photos into date-based folders. The default date_format is YYYY/MM; the example below uses YYYY/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.rawSecurity-screen a folder
file_organizer_sensitive_scan reads the metadata block of every JPEG and TIFF in a
folder and scores each one 0-100 for the risk of sharing it. It flags EXIF GPS
coordinates and altitude, GPS fix timestamps, owner and artist names, camera and
lens serial numbers, camera or computer make and model, copyright lines,
capture/editing software, and free-text notes. Each score arrives with the
individual findings and the weight each one added, so the number is a sum of
stated causes:
{
"name": "IMG_4471.jpg",
"risk_score": 70,
"risk_level": "high",
"reasons": [
{ "kind": "gps_coordinates", "weight": 40, "exif_tags": ["GPSLatitude", "GPSLongitude"], "value": "51.5073, -0.1277" },
{ "kind": "owner_name", "weight": 30, "exif_tags": ["OwnerName"], "value": "Jane Q Public" }
]
}A score of 0 is not a clearance to share the file. The detection is
heuristic and the tool never modifies anything: it reports what it recognizes,
and it does not look at PDF annotations, XMP, IPTC, embedded thumbnails, file
names, or what is visible in the picture. Files outside JPEG and TIFF are listed
under skipped with a reason. Treat the scan output itself as sensitive, since
it echoes the values it found.
Set up automatic organization
Register a directory with a cron schedule:
{
"directory": "/Users/john/Downloads",
"schedule": "0 9 * * *",
"rules": {
"auto_organize": true,
"min_file_age_minutes": 5
}
}The server organizes the folder on that schedule. Add more watches for other directories.
These rules follow the directory, not the process that started the sweep: a cron
line running once --source scheduled over this folder gets the same age filter
and file cap the built-in daemon would apply. A pass you run by hand with no
--source is never filtered.
Security configuration
Access is restricted to a whitelist of user directories by default. System directories stay blocked.
Allowed by default
The server enables these locations if they exist on the machine:
Platform | Allowed directories |
Windows | Desktop, Documents, Downloads, Pictures, Videos, Music, Projects, Workspace, workspace, Development, Code, OneDrive (if set) |
macOS | Desktop, Documents, Downloads, Pictures, Videos, Music, Projects, Workspace, workspace, Development, Code, Movies, iCloud Drive, /Volumes |
Linux | Desktop, Documents, Downloads, Pictures, Videos, Music, Projects, Workspace, workspace, Development, Code, |
Only directories that exist and are not symlinks are returned.
Always blocked
These paths stay blocked even if you add them to the config:
Windows:
C:\Windows, Program Files, AppData,$Recycle.BinmacOS:
/System,/Library,/Applications,/private,/usrLinux:
/etc,/usr,/var,/root,/sys,/procEverywhere:
node_modules,.git,.vscode,.idea,dist,build
Custom configuration
Edit the user config file:
Windows:
%APPDATA%\file-organizer-mcp\config.jsonmacOS:
$HOME/Library/Application Support/file-organizer-mcp/config.jsonLinux:
$HOME/.config/file-organizer-mcp/config.json
Add paths to customAllowedDirectories:
{
"customAllowedDirectories": [
"C:\\Users\\Name\\My Special Folder",
"D:\\Backups"
]
}You can paste a folder path straight from your file explorer's address bar.
External drives and network mounts
Paths outside your home directory are blocked unless you opt in. To allow an external volume such as /Volumes/My Drive on macOS or /media/user/usb on Linux, set allowExternalVolumes to true:
{
"allowExternalVolumes": true,
"customAllowedDirectories": [
"/Volumes/MyExternalDrive",
"/Volumes/Photography Backup"
]
}Windows drive letters like D:\ work without this flag.
Restart the client after editing the config.
Moving your config to another machine
file_organizer_export_config bundles the whole user config — allowed
directories, custom rules, conflict strategy, watch entries, auto-organize and
history settings — into one JSON document you can copy to a laptop or a fresh
install:
// writes the bundle; refuses to overwrite an existing file
file_organizer_export_config({ output_path: "~/fom-config-bundle.json" });
// omit output_path to get the bundle in the reply without writing oneRules, strategies and schedules mean the same thing anywhere. Directory paths do not: they are absolute paths of the machine that exported them, so they will not exist on the target and they do describe your directory layout. The reply always says so:
absolute mode (the default) exports the paths exactly as configured and lists every field to edit by hand in
requires_editing.rebased mode takes a
rebase_root— normally the home directory — and rewrites each path under it as~/relative, which follows the target machine's home. A path outside that root cannot be rebased; it is exported unchanged and named innon_portable_paths.
file_organizer_export_config({
rebase_root: "~",
response_format: "json",
});
// → requires_editing: [], directories exported as ["~/Documents", "~/Downloads"]Copy the bundle to the other machine, apply the edits it names, and merge its
config into that machine's config.json. The tool never writes the config
file itself, and the bundle file is the only thing it writes.
Conflict strategy
{
"conflictStrategy": "rename"
}rename(default) - Append a suffix to the new file, for examplefile (1).txt.skip- Keep the existing file and skip the new one.overwrite- Replace the existing file, after writing a backup.
Legacy auto-organize schedule
For a simple hourly, daily, or weekly schedule:
{
"autoOrganize": {
"enabled": true,
"schedule": "daily"
}
}For anything more granular, run file-organizer-watch add <directory> "<cron>".
Notification after a pass
A scheduled pass that actually moved files can run one command, so you find out without watching the log:
{
"notify": {
"command": "notify-send \"Organized\" \"$FOM_NOTIFY_MOVED files\"",
"throttleMinutes": 60
}
}The command is tokenized into argv and spawned without a shell. Quotes group
arguments and |, > and && are literal; write sh -c "..." when you do
want a pipeline. It gets FOM_NOTIFY_DIRECTORY and FOM_NOTIFY_MOVED in its
environment.
Nothing runs on a dry run, or on a pass that moved nothing. The throttle is per directory and the first notification for a directory always goes out, so a failed command or a full disk cannot silence you for good. A command that fails is logged and never fails the pass.
Rollback retention
Rollback manifests expire. The default window is 30 days, and expired manifests are deleted the next time anything reads the rollback directory.
{
"rollback": {
"retentionDays": 30
}
}0 keeps every manifest forever. A negative value clamps to 0, so it keeps
everything rather than expiring everything. Only manifests this install wrote
and can still verify are eligible; an unverified or corrupt file stays visible
instead of being deleted. If a rollback is in flight when a read happens, the
prune skips that pass and tries again later.
Defenses
Attack type | Protection |
Unauthorized access | Whitelist plus blacklist enforcement |
Path traversal | validatePathBase, see ARCHITECTURE.md |
Symlink attacks | Real path resolution |
DoS | Resource limits on file count, depth, and size |
Troubleshooting
The MCP server does not appear
Check the config file path is correct.
Confirm Node.js 20 or newer:
node --version.Fully restart the client.
Check the path in the client config file.
Permission errors
Windows: run the client as Administrator.
macOS/Linux: check folder permissions with
ls -la.Confirm the target directory is writable.
Files are not moving
Make sure
dry_runis not enabled.Close programs that may be locking the files.
Check for sufficient disk space.
Read the operation summary for error messages.
Custom rules are missing after a restart
file_organizer_set_custom_rules saves the accepted rules to config.json in your
OS config directory and every later request reads them from there. Three things
to know:
The call replaces the whole saved set, so it is not a per-rule merge.
Rules with an unknown category or a rejected pattern are skipped; the reply says how many were applied.
If the write itself fails — read-only config directory, missing permissions — the call returns an error instead of a success message, and the server log holds the cause. Nothing is persisted in that case.
Architecture
The server is stateless: each JSON-RPC request gets a fresh context (config, history logger) routed through an explicit tool registry into pure service modules under src/core/. The pipeline is scan → categorize → plan → move, every path passes validatePathBase before any fs call, and all side effects are file-backed (history, rollback manifests), so nothing survives a restart except what you can undo.
Scheduled organization runs as a separate process (file-organizer-watch) so the stdio server stays request/response.
See ARCHITECTURE.md for the diagram and design notes.
Documentation
API.md - Complete tool reference
ARCHITECTURE.md - Design and architecture
examples/scheduling - Scan + preview sweep recipes for Claude Desktop, Codex, cron, and systemd
CONTRIBUTING.md - Contribution guidelines
MIGRATION.md - v2 to v3 upgrade guide
CHANGELOG.md - Version history
SECURITY.md - Security model and reporting
Contributing
Read CONTRIBUTING.md, then clone and build:
git clone https://github.com/kridaydave/File-Organizer-MCP.git
cd File-Organizer-MCP
npm install
npm run build
npm testAdding a tool: one file, one line
Create
src/tools/my-tool.tsexporting aToolDefinition(name, Zod input schema, annotations, formats) and its handler.Add an import and one
reg()entry insrc/mcp/registry.ts.
That's it. The registry is the single source of truth: the server registers from it, routing is pure, and no other file changes. Schemas shared across tools live in src/schemas/ (common, scan, organize, system). If your tool takes a path, it goes through validateStrictPath before touching fs, and errors go through sanitizeErrorMessage. See ARCHITECTURE.md for the contract details.
Report bugs and feature requests on GitHub Issues. For a security vulnerability, email technocratix902@gmail.com.
License
MIT. See 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