LocalFilesOrganizer-MCP

# Local Files MCP Server A Model Context Protocol (MCP) server for managing local files. Provides tools for reading, writing, analyzing, searching, and organizing files with built-in safety protections. ## Features - 📖 **Read/Write files** - UTF-8 and base64 support - 📂 **Directory operations** - List, organize, search - 🔍 **Content search** - Regex pattern matching - 🔎 **Find duplicates** - MD5 hash comparison - 📊 **File analysis** - Size, MIME type, line counts - 🛡️ **Safety protections** - Configurable allowed/protected paths - 🖥️ **Cross-platform** - macOS, Linux, Windows ## Installation ### NPX Add to your Claude Desktop configuration file: **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` **Linux**: `~/.config/Claude/claude_desktop_config.json` ```json { "mcpServers": { "local-files": { "command": "npx", "args": ["-y", "fsorg"] } } } ``` That's it! Claude Desktop will automatically download and run the MCP server via npx. ### Alternative: Install from source ```bash git clone https://github.com/argtobias/fsorg.git cd fsorg pnpm install pnpm build ``` Then configure Claude Desktop: ```json { "mcpServers": { "local-files": { "command": "node", "args": ["/path/to/fsorg/dist/index.js"] } } } ``` ### Safety Configuration Create a config file at: -- **macOS/Linux**: `~/.config/localfiles-org/config.json` -- **Windows**: `%LOCALAPPDATA%\localfiles-org\config.json` ```json { "allowedPaths": [ "~/projects", "~/Development", "~/workspace", "/tmp" ], "additionalProtectedPaths": [ "~/my-important-folder" ], "additionalProtectedPatterns": [ "^backup", "\\.bak$" ] } ``` #### Configuration Options | Option | Description | Default | |--------|-------------|---------| | `allowedPaths` | Paths where delete operations are permitted | `~/projects`, `~/dev`, etc. | | `additionalProtectedPaths` | Extra paths to protect from deletion | `[]` | | `additionalProtectedPatterns` | Regex patterns for protected file names | `[]` | #### Always Protected (cannot be overridden) - **System paths**: `/`, `/etc`, `/usr`, `/bin`, `/System`, etc. - **User paths**: `~`, `~/Documents`, `~/Desktop`, `~/Downloads`, `~/.ssh` - **Patterns**: `.git`, `.env`, `.ssh`, credentials, secrets ## Available Tools ### File Operations | Tool | Description | |------|-------------| | `read_file` | Read file contents (UTF-8 or base64) | | `write_file` | Write content to file (UTF-8 or base64) | | `delete_file` | Safely delete a file with protection checks | | `move_file` | Move file with optional empty directory cleanup | | `analyze_file` | Get file stats (size, MIME, lines, words) | ### Directory Operations | Tool | Description | |------|-------------| | `list_directory` | List files with optional recursion and glob patterns | | `delete_directory` | Safely delete directory (requires confirmation for recursive) | | `organize_by_type` | Organize files into folders by extension/date/size | ### Search Operations | Tool | Description | |------|-------------| | `search_content` | Search for regex patterns in file contents | | `find_duplicates` | Find duplicate files by MD5 hash | | `sort_file_content` | Sort lines in a file | ### Batch Operations | Tool | Description | |------|-------------| | `rename_files` | Batch rename files using regex patterns | ## Usage Examples ### Read a file ```json { "tool": "read_file", "arguments": { "path": "~/projects/myfile.txt" } } ``` ### Find and delete duplicates ```json { "tool": "find_duplicates", "arguments": { "path": "~/projects/images", "recursive": true } } ``` ### Safely delete with preview ```json { "tool": "delete_file", "arguments": { "path": "~/projects/temp/old-file.txt", "preview": true } } ``` ### Organize files by extension ```json { "tool": "organize_by_type", # Local Files MCP Server Simple MCP server for safe local file operations: read, write, search, organize and protected delete. ## Quick install Run via npx (recommended for Claude Desktop): ```json { "mcpServers": { "local-files": { "command": "npx", "args": ["-y", "fsorg"] } } } ``` From source: ```bash git clone https://github.com/argtobias/fsorg.git cd fsorg pnpm install pnpm build ``` ## Configuration Create user config at: - macOS/Linux: `~/.config/localfiles-org/config.json` - Windows: `%LOCALAPPDATA%\\localfiles-org\\config.json` Minimal config example: ```json { "allowedPaths": ["~/projects", "~/Development"], "additionalProtectedPaths": [], "additionalProtectedPatterns": [] } ``` ## Safety - Only operations inside `allowedPaths` can delete files. - System and user-critical paths are always protected. - Pattern-based protection (e.g. `.git`, `.env`) is enforced. ## Usage examples Read a file: ```json { "tool": "read_file", "arguments": { "path": "~/projects/myfile.txt" } } ``` Find duplicates: ```json { "tool": "find_duplicates", "arguments": { "path": "~/projects/images", "recursive": true } } ``` Delete with preview (safe): ```json { "tool": "delete_file", "arguments": { "path": "~/projects/temp/old.txt", "preview": true } } ``` ## Development ```bash pnpm install pnpm build pnpm dev ``` ## License ISC