File Organizer MCP

🚀 File Organizer MCP Server

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

🚀 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

✨ 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.

📦 Installation

You can install the File Organizer MCP Server using the following methods:

• npx: npx file-organizer-mcp --setup for occasional use or trial.
• Global: npm install -g file-organizer-mcp for regular use and faster startup.

💻 Usage Examples

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.
3. Finds duplicates → Found 45 duplicate groups, wasted 2.3 GB
4. Shows largest files → old_backup.zip: 5.2 GB
5. Previews organization → Shows planned moves and conflicts
6. Asks for confirmation
7. 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

📚 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

🔧 Technical Details

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

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

📄 License

MIT License - see LICENSE file for details

🤝 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 technocratix902@gmail.com
🐛 Bugs/features: GitHub Issues

📞 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