File OrganizerBLOCK
This MCP server will organize your files using connections to MCP using clients like Claude, Cursor and Gemini Cli
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
Version 5.0.0 | MCP protocol 2026-07-28 (stateless) | Node.js 20+
[](https://www.npmjs.com/package/file-organizer-mcp) [](https://www.npmjs.com/package/file-organizer-mcp) [](LICENSE) [](tests/)
A Model Context Protocol (MCP) 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
- Quick start
- Features
- Tools
- File categories
- Example workflows
- Security
- Troubleshooting
- Architecture
- Documentation
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:
Quick start
One-command setup
npx file-organizer-mcp --se
a93015f7648fOBSERVED · 2026-10-08Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control. Replace the environment placeholders with a token scoped to the least it needs.
claude mcp add file-organizer-mcp --env OPENCODE_API_KEY=${OPENCODE_API_KEY} -- npx -y [email protected]{
"mcpServers": {
"file-organizer-mcp": {
"command": "npx",
"args": [
"-y",
"[email protected]"
],
"env": {
"OPENCODE_API_KEY": "${OPENCODE_API_KEY}"
}
}
}
}Exposed tools (25)
20 read · 3 write · 2 destructive. Blast radius: 2 tools can delete or overwrite — an agent that can be talked into calling a tool can be talked into calling this one.
| Tool | Risk | Description |
|---|---|---|
Cursor | read | AI-powered code editor with MCP support |
Windsurf | read | Codeium |
file_organizer_analyze_duplicates | destructive | Finds duplicate files and suggests which to keep/delete based on location, name quality, and age. |
file_organizer_batch_read_files | read | 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. |
file_organizer_batch_rename | write | Rename multiple files using rules (find/replace, case, add text, numbering). |
file_organizer_categorize_by_type | read | 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. |
file_organizer_delete_duplicates | destructive | Deletes specified duplicate files. DESTRUCTIVE. Every candidate is hashed and checked against surviving copies before anything is removed. The search walks each candidate |
file_organizer_disk_usage_by_category | read | Report how much space a directory holds per category: bytes, file count, and share of the total. Categories come from the same categorizer organize_files uses, including your custom rules, and sizes are summed from the scan, so this costs one directory walk and no extra dependency. |
file_organizer_find_duplicate_files | read | Find duplicate files in a directory based on their content (SHA-256 hash). Shows potential wasted space. Files above the hashing size cap (100MB by default) and empty files are not compared; any such file is reported back in |
file_organizer_find_largest_files | read | Find the largest files in a directory. Useful for identifying space-consuming files and cleanup opportunities. |
file_organizer_get_categories | read | Returns the list of categories used for file organization |
file_organizer_inspect_metadata | read | 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. |
file_organizer_list_files | read | List all files in a directory with basic information. Returns file names and paths. Does not recurse into subdirectories. |
file_organizer_organize_by_project | read | Group files across all types (documents, code, images) into detected project folders using shared name tokens, content terms (text-like files only), and identifier markers. Deterministic, local-only detection. Use dry_run=true to preview changes. |
file_organizer_organize_files | write | 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. |
file_organizer_organize_music | read | 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. |
file_organizer_organize_photos | read | 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. |
file_organizer_preview_organization | read | Shows what would happen if files were organized, WITHOUT making any changes. Shows moves, conflicts, and skip reasons. Pass since_last_run=true to report only the files touched at or after the scheduler |
file_organizer_read_file | read | Read file contents with security checks. Supports text, binary, and base64 encoding. |
file_organizer_scan_directory | read | Scan directory and get detailed file information including size, dates, and extensions. Supports recursive scanning. |
file_organizer_search_history | read | Search the file organization history. Filter entries by path glob, date range (from/to), operation type, status, or source — all optional and combinable. Entries only match a path_glob when the operation recorded the path it touched. |
file_organizer_set_custom_rules | write | Customize how files are categorized. Persists custom rules to user configuration, replacing any rules saved earlier. Invalid rules are skipped; if the rules cannot be written to disk the call reports an error instead of a success. |
file_organizer_smart_suggest | read | Analyze a directory and provide intelligent suggestions for organization, cleanup, and deduplication based on directory health metrics. |
file_organizer_system_organize | read | Organize files into OS-standard system directories (Music, Documents, Pictures, Videos) |
file_organizer_view_history | read | 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. |
Trust audit
BLOCKgrade D · trust 69/100 Do not install this without reading the findings. The audit found something that could harm you or your machine.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | PASS |
| L1 | Static analysis of the code | FAIL |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | WARN |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- declared (17 observation(s))
- Network
- declared (2 observation(s))
- Shell
- declared (6 observation(s))
- Dependencies
- not all pinned
- Secrets in source
- none-found
Findings (18)
description: "eval() or Function constructor can execute arbitrary code",
{ payload: "ID_RSA", description: "Uppercase SSH key" },{ payload: ".SSH/ID_RSA", description: "Uppercase SSH directory" },{ payload: "id_rsa.pub", description: "SSH public key" },{ payload: "id_rsa", description: "SSH private key" },{ payload: ".ssh/id_ed25519", description: "ED25519 key" },autoVerify = false,
icon: "👨💻",
icon: "👨💻",
file_organizer_analyze_duplicates, file_organizer_delete_duplicates
file-organizer-dev.skill
.markdownlint.json
import { readFile } from "../../src/core/io/index.js";import { PathValidatorService } from "../../src/services/path-validator.service.js";import { isSensitiveFile } from "../../src/core/io/sensitive-files.js";const TEST_BASE_PATH = path.join(__dirname, "../../test-security-temp");
"../../../etc/passwd",
@inquirer/prompts, @modelcontextprotocol/server, chalk, exif-parser, minimatch, music-metadata, node-cron, piexifjs
Gates applied: no_behavioural_pass.
a93015f7648ffull audit observations/trust-audit/mcp-server/kridaydave__file-organizer.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-08 | a93015f7648f | BLOCK | D | 69 | first audit |
Questions
What is the File Organizer MCP server?
This MCP server will organize your files using connections to MCP using clients like Claude, Cursor and Gemini Cli
What tools does File Organizer expose?
25 in total: 20 read-only, 3 that write, and 2 that can delete or overwrite (file_organizer_analyze_duplicates, file_organizer_delete_duplicates). Every one is listed on this page with its risk.
Is File Organizer safe to connect to an agent?
No — not without reading the findings first. The audit graded it D (69/100) and found 7 critical or high issues in the source. Each one is listed on this page with the file and line it is on. Separately from the audit: 2 of its tools can destroy data, so scope the token you give it to what you actually need.
What credentials does File Organizer need?
It reads OPENCODE_API_KEY from the environment. Give it a token scoped to the least it needs — an agent that can be talked into calling a tool can be talked into calling it with your credentials.
How does File Organizer run?
It speaks stdio, so it runs as a local process your client starts. It is published on npm as file-organizer-mcp at 5.0.0.
How current is this page?
The grade is for one exact copy of the source (a93015f7648f), read on 2026-10-08. The repository is watched and re-audited when it changes.