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

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

Directory Operations

Search Operations

Batch Operations

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