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

{
  "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

git clone https://github.com/argtobias/fsorg.git
cd fsorg
pnpm install
pnpm build

Then configure Claude Desktop:

{
  "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

{
  "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

{
  "tool": "read_file",
  "arguments": {
    "path": "~/projects/myfile.txt"
  }
}

Find and delete duplicates

{
  "tool": "find_duplicates",
  "arguments": {
    "path": "~/projects/images",
    "recursive": true
  }
}

Safely delete with preview

{
  "tool": "delete_file",
  "arguments": {
    "path": "~/projects/temp/old-file.txt",
    "preview": true
  }
}

Organize files by extension

{
  "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:

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:

{
  "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:

{ "tool": "read_file", "arguments": { "path": "~/projects/myfile.txt" } }

Find duplicates:

{ "tool": "find_duplicates", "arguments": { "path": "~/projects/images", "recursive": true } }

Delete with preview (safe):

{ "tool": "delete_file", "arguments": { "path": "~/projects/temp/old.txt", "preview": true } }

Development

pnpm install
pnpm build
pnpm dev

License

ISC