File Organizer MCP Server

Version: 3.4.2 | MCP Protocol: 2024-11-05 | Node: ≥18.0.0

New in v3.3.0 - Smart Organization:

• organize_smart - Auto-detects and organizes mixed folders (music, photos, documents)
• organize_music - Music by Artist/Album structure with ID3 metadata
• organize_photos - Photos by EXIF date with GPS stripping
• organize_by_content - Documents by topic extraction
• batch_read_files - Read multiple files efficiently

Previous v3.2.8:

• Enhanced metadata extraction, security screening, and metadata cache system

Why Specialized Tools • Quick Start • Features • Tools • Examples • API • Security • Architecture

A powerful, security-hardened Model Context Protocol (MCP) server for intelligent file organization.

Why File Organizer MCP?

Traditional filesystem MCP servers provide primitive tools: read, write, make, delete. When an AI organizes folders using only these tools, it results in:

1. Complexity - AI must plan multiple steps for every move and rename.
2. Token Inefficiency - Describing every operation consumes significant context.
3. Risk of Hallucination - Increased steps increase the probability of errors.
4. Latency - Each primitive operation requires independent reasoning.

The Solution

We provide high-level, atomic tools that encapsulate complex file operations:

| Primitive Approach | File Organizer MCP | | --- | --- | | Multiple read/write/rename calls | organize_files() - Atomic execution | | 50+ reasoning steps | 1 reasoning step | | High token usage | Minimal token usage | | Error-prone | Rollback-safe operations |

Install from MCP Registry • View on NPM • Report Issues

Quick Start

One-Command Setup

Run the following command to start the interactive setup:

npx file-organizer-mcp --setup

The wizard will:

• Auto-detect installed AI clients (Claude Desktop, Cursor, Windsurf, Cline, etc.).
• Configure clients automatically.
• Guide you through folder selection and preferences.

Requirements

• Node.js 18+

Common Commands

Once configured, you can ask your AI:

• "Organize my Downloads folder"
• "Find duplicate files in my Documents"
• "Show me my largest files"

Installation Methods

| Method | Command | Use Case | | --- | --- | --- | | npx | npx file-organizer-mcp --setup | Occasional use / Trial | | Global | npm install -g file-organizer-mcp | Regular use / Faster startup |

Features

• Categorization - Intelligent sorting into 12+ categories.
• Scheduling - Cron-based automatic organization.
• Duplicate Detection - Content hashing (SHA-256) for precise identification.
• Metadata Extraction - EXIF for photos, ID3 for music, and document topic extraction.
• Smart Organization - Unified strategy detecting mixed file types.
• Safe Operations - Dry-run mode, rollback support, and atomic moves.
• Security - TOCTOU mitigation, path traversal protection, and metadata scrubbing.
• Multi-Platform - Native support for Windows, macOS, and Linux.

Tools Reference

Core Tools

file_organizer_scan_directory

Scan directory with detailed file information.

• directory (required): Full path to directory.
• include_subdirs (optional): Recursive scan.

file_organizer_read_file

Secure file reading with 8-layer validation.

• path (required): Absolute path.
• encoding (optional): utf-8, base64, or binary.

file_organizer_organize_smart

Unified tool that handles music, photos, and documents automatically using the best strategy for each.

file_organizer_batch_rename

Rename multiple files using patterns, regex, or numbering.

file_organizer_undo_last_operation

Reverse previous organization actions.

File Categories

| Category | Typical Extensions | | --- | --- | | Executables | .exe, .msi, .bat, .sh | | Videos | .mp4, .avi, .mkv, .mov | | Documents | .pdf, .doc, .docx, .txt, .md | | Images | .jpg, .jpeg, .png, .gif, .webp | | Audio | .mp3, .wav, .flac, .m4a | | Archives | .zip, .rar, .7z, .tar.gz | | Code | .py, .js, .ts, .java, .go, .json |

Example Workflows

Intelligent Downloads Cleanup

1. Scan -> Review file distribution and space usage.
2. Analyze -> Identify duplicates and obsolete files.
3. Execute -> Atomic organization into categorized folders.
4. Finds duplicates → Found 45 duplicate groups, wasted 2.3 GB
5. Shows largest files → old_backup.zip: 5.2 GB
6. Previews organization → Shows planned moves and conflicts
7. Asks for confirmation
8. Organizes files → ✅ Organized 1,247 files into 8 category folders

Result: Clean, organized Downloads folder with duplicates identified

---

### Workflow 2: Project Organization

User: "Claude, organize my project folder at ~/myproject"

Claude:

1. Scans the project → 423 files across multiple subdirectories
2. Identifies file types → Code (289), Assets (87), Docs (47)
3. Suggestions organization → Preserves src/ structure, organizes root files
4. Previews changes → Shows (47) items to organize
5. Executes → Moves config files, readmes, screenshots to proper folders

Result: Clean project structure with organized documentation and assets

---

### Workflow 3: Duplicate File Management

User: "Claude, find and analyze duplicates in C:/Users/[YOUR_USERNAME]/Documents"

Claude:

1. Scans for duplicates → Finds 23 duplicate groups
2. Analyzes each group → Scores files by location, name quality, age
3. Suggests which to keep → Keeps "/Documents/Important/file.pdf"
4. Suggests which to delete → Delete "/Downloads/file (1).pdf"
5. Shows wasted space → Total: 1.8 GB can be reclaimed

User can manually delete or ask Claude to organize to remove duplicates

---

### Workflow 4: Large File Discovery

User: "Claude, show me the 20 largest files taking up space in my Downloads folder"

Claude:

1. Analyzes directory size → Total: 45.2 GB
2. Finds largest files:
   • old_backup_2023.zip: 12.3 GB (2 years old)
   • movie_collection.mkv: 8.7 GB
   • presentation_final.pptx: 890 MB
3. Suggests cleanup → Archive or delete old backups
4. Shows duplicates in large files → Some large files have copies

Result: Clear visibility into space usage with actionable insights

---

### Workflow 5: Music Organization

User: "Claude, organize my music folder at C:/Users/[YOUR_USERNAME]/Music"

Claude:

1. Scans directory → Shows 456 music files, 2.3 GB
2. Extracts metadata → Reads ID3 tags for artist, album, and title
3. Previews organization → Shows planned structure: Artist/Album/Title.mp3
4. Asks for confirmation
5. Organizes files → ✅ Organized 456 music files into 32 artist folders

Result: Music files organized by Artist/Album/Title structure using ID3 metadata

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

---

### Workflow 6: Photo Organization

User: "Claude, organize my photos at C:/Users/[YOUR_USERNAME]/Pictures"

Claude:

1. Scans directory → Shows 1,234 photos, 4.5 GB
2. Extracts EXIF metadata → Reads date taken from EXIF tags
3. Previews organization → Shows planned structure: YYYY/MM/DD
4. Asks for confirmation
5. Organizes files → ✅ Organized 1,234 photos into date-based folders

Result: Photos organized by capture date (YYYY/MM/DD) using EXIF metadata

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

---

### Workflow 7: Security Screening with Metadata

User: "Claude, scan my Documents folder for security issues"

Claude:

1. Scans directory → Shows 567 documents, 1.2 GB
2. Extracts metadata → Reads file metadata and content signatures
3. Performs security screening →
   • Found 3 files with sensitive metadata
   • Found 1 file with potentially malicious content
4. Shows detailed report →
   • "report.pdf" contains EXIF GPS coordinates
   • "resume.docx" contains personal identification information
5. Suggests actions → Redact metadata, quarantine file

Result: Comprehensive security scan with metadata-based threat detection

---

### Workflow 8: Set Up Automatic Organization

User: "Claude, automatically organize my Downloads folder every day at 9am"

Claude:

1. Sets up watch directory → file_organizer_watch_directory({ directory: "/Users/john/Downloads", schedule: "0 9 * * *", min_file_age_minutes: 5 })
2. Confirms setup → "Downloads folder will be organized daily at 9:00 AM"
3. Shows current watches → Lists all watched directories

User: "Also watch my Desktop folder every hour"

Claude: 4. Adds second watch → file_organizer_watch_directory({ directory: "/Users/john/Desktop", schedule: "0 * * * *", max_files_per_run: 50 })

Result: Automatic background organization with smart scheduling

---

## <a id="security-configuration"></a>Security Configuration 🔐

### Security Score: 10/10 🌟

The server uses a **Secure by Default** approach. Access is restricted to a specific whitelist of user directories. All system directories are blacklisted.

### ✅ Allowed Directories (Default)

The server automatically detects and allows access to these safe user locations:

| Platform    | Allowed Directories                                                                                     |
| ----------- | ------------------------------------------------------------------------------------------------------- |
| **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`              |

_> Note: Only directories that actually exist on your system are enabled._

### ❌ Always Blocked

To prevent accidents, the following are **always blocked**, even if added to config:

- **Windows:** `C:\Windows`, `Program Files`, `AppData`, `$Recycle.Bin`
- **macOS:** `/System`, `/Library`, `/Applications`, `/private`, `/usr`
- **Linux:** `/etc`, `/usr`, `/var`, `/root`, `/sys`, `/proc`
- **Global:** `node_modules`, `.git`, `.vscode`, `.idea`, `dist`, `build`

### ⚙️ Custom Configuration

You can customize behavior by editing the user configuration file.

**Config Location:**

- **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`

**How to Add Directories:**

1. Open `config.json`
2. Add paths to `customAllowedDirectories`:

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

💡 Tip: You can copy a folder path directly from your file explorer's address bar and paste it into customAllowedDirectories.

💾 External Drives & Network Mounts

By default, for security reasons, you cannot add paths outside your home directory. If you need to access external volumes (like /Volumes/My Drive on macOS or /media/user/usb on Linux), you must explicitly opt-in by adding "allowExternalVolumes": true:

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

(Note: Windows drive letters like D:\ work out of the box and do not require this flag.)

3. Restart Claude Desktop.

Conflict Strategy

Set your preferred default conflict resolution strategy:

{
  "conflictStrategy": "rename"
}

Available strategies:

• "rename" (default) - Renames new file (e.g., file (1).txt)
• "skip" - Keeps existing file, skips new one
• "overwrite" - Replaces existing file (creates backup first)

Auto-Organize Schedule (Legacy)

Simple schedule configuration (for basic hourly/daily/weekly):

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

For advanced cron-based scheduling, use the file_organizer_watch_directory tool.

Security Defenses

| Attack Type | Protection Mechanism | Status | | ----------------------- | ------------------------------------ | ------------ | | Unauthorized Access | Whitelist + Blacklist Enforcement | ✅ Protected | | Path Traversal | 8-Layer Validation Pipeline | ✅ Protected | | Symlink Attacks | Real Path Resolution | ✅ Protected | | DoS | Resource Limits (Files, Depth, Size) | ✅ Protected |

🐛 Troubleshooting

MCP Server Not Showing Up

1. ✅ Check config file path is correct
2. ✅ Verify Node.js v18+ is installed: node --version
3. ✅ Restart Claude Desktop completely
4. ✅ Check path in claude_desktop_config.json is correct

Permission Errors

1. ✅ Windows: Run Claude Desktop as Administrator
2. ✅ Mac/Linux: Check folder permissions: ls -la
3. ✅ Ensure write permissions in target directory

Files Not Moving

1. ✅ Verify dry_run mode is NOT enabled
2. ✅ Check files aren't locked by other programs
3. ✅ Ensure sufficient disk space
4. ✅ Review error messages in operation summary

Technical Stack 🛠️

File Organizer MCP is built with modern web technologies and follows strict security practices:

Core Dependencies

• MCP Server: @modelcontextprotocol/sdk - Model Context Protocol implementation
• Security: Zod schema validation, path traversal protection
• Metadata Extraction:
  • music-metadata - ID3 tag extraction for audio files
  • exif-parser - EXIF metadata extraction for images
• Scheduling: node-cron - Cron-based schedule management
• Interactive UI: Ink + React - Terminal user interface
• Prompts: @inquirer/prompts - Interactive CLI prompts
• Utilities: Chalk (color), minimatch (glob patterns)

Security Features

• 8-layer path validation - Blocks traversal attacks and URI encoding tricks
• Sensitive file detection - Blocks access to .env, .ssh, passwords, keys
• Rate limiting - 120 requests/minute, 2000 requests/hour
• TOCTOU protection - File descriptor-based operations
• Metadata security - Redact sensitive metadata (GPS, personal info)

Performance Optimizations

• Metadata caching - 7-day cache with file hash validation
• Parallel processing - Configurable concurrency for batch operations
• Stream processing - Handles large files without memory issues
• Memory limits - Prevents excessive resource consumption

Architecture 🏗️

Screen-Then-Enrich Architecture

The File Organizer MCP server implements a "Screen-Then-Enrich" architecture for secure and efficient file operations:

┌───────────────────────────────────────────────────────────┐
│                     MCP Client (LLM)                      │
└─────────────────────────┬─────────────────────────────────┘
                           │ JSON-RPC 2.0
┌─────────────────────────▼─────────────────────────────────┐
│                    MCP Server Layer                        │
│  (server.ts - Protocol Handler)                            │
└─────────────────────────┬─────────────────────────────────┘
                           │
┌─────────────────────────▼─────────────────────────────────┐
│                     Security Screening                     │
│  - Path validation & containment checks                    │
│  - Sensitive file detection                                │
│  - Rate limiting                                           │
└─────────────────────────┬─────────────────────────────────┘
                           │
┌─────────────────────────▼─────────────────────────────────┐
│                   Metadata Enrichment                      │
│  - EXIF extraction for images (camera, date, GPS)          │
│  - ID3 extraction for audio (artist, album, title)         │
│  - Document metadata (PDF, DOCX properties)                │
└─────────────────────────┬─────────────────────────────────┘
                           │
┌─────────────────────────▼─────────────────────────────────┐
│                    Services Layer                           │
│  ┌────────────┬──────────────┬─────────────┬──────────┐    │
│  │ Path       │ Organizer    │ Hash        │ Scanner  │    │
│  │ Validator  │ Service      │ Calculator  │ Service  │    │
│  └────────────┴──────────────┴─────────────┴──────────┘    │
└─────────────────────────┬─────────────────────────────────┘
                           │
┌─────────────────────────▼─────────────────────────────────┐
│                    File System                               │
└───────────────────────────────────────────────────────────┘

Key Architecture Principles

1. Security First - Multi-layer validation before any file operations
2. Metadata-Driven - Content-aware organization using extracted metadata
3. Caching Strategy - 7-day metadata cache with file hash validation
4. Batch Processing - Configurable concurrency for large operations
5. Atomic Operations - Safe file operations with rollback support

API Documentation 📚

New Metadata APIs

file_organizer_inspect_metadata

Description: Extracts comprehensive metadata from files with privacy controls

Parameters:

• file: string (required) - Full path to the file
• response_format: 'json' | 'markdown' (optional, default: 'markdown')

Returns:

• For images: EXIF data (camera, date, dimensions, ISO, aperture)
• For audio: ID3 tags (artist, album, title, year, genre)
• For documents: file properties

Metadata Cache System

Configuration:

{
  "metadataCache": {
    "enabled": true,
    "maxAge": 604800000, // 7 days in ms
    "maxEntries": 10000,
    "cacheDir": ".cache"
  }
}

Cache Stats:

// Get cache statistics
const stats = await getCacheStats();
// {
//   totalEntries: 1500,
//   audioEntries: 800,
//   imageEntries: 700,
//   cacheSize: 256000
// }

📝 Important Notes

• ⚠️ Organizes files in root directory only, not subdirectories (by default)
• ⚠️ Existing category folders won't be reorganized (prevents loops)
• ✅ File extensions are case-insensitive
• ✅ Original modification dates are preserved
• ✅ Hidden files (starting with .) are automatically skipped
• ✅ Maximum 10,000 files processed per operation (security limit)
• ✅ Maximum 10 directory levels scanned (security limit)
• ✅ Rollback support for undo operations

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

Development Setup

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

Reporting Issues

🚨 Security vulnerabilities: Email [email protected]
🐛 Bugs/features: GitHub Issues

📚 Documentation

• API.md - Complete tool reference
• ARCHITECTURE.md - Technical architecture and design patterns
• CONTRIBUTING.md - Contribution guidelines
• MIGRATION.md - v2 to v3 upgrade guide
• CHANGELOG.md - Version history

📄 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

• Anthropic - For the Model Context Protocol specification
• NetworkChuck - For the MCP tutorial that inspired this project
• The MCP Community - For feedback and support

📞 Support

• MCP Registry: View Listing
• NPM Package: View on NPM
• Issues: GitHub Issues
• MCP Spec: Model Context Protocol

Happy Organizing! 🎯

Built with ❤️ for the MCP community

⬆ Back to Top