ellmos-filecommander-mcp

<p align="center">
  <img src="assets/filecommander_banner.jpg" alt="FileCommander banner" width="700">
</p>

# ellmos FileCommander MCP Server

**🇩🇪 [Deutsche Version](README_de.md)**

*Part of the [ellmos-ai](https://github.com/ellmos-ai) family.*

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![npm version](https://img.shields.io/npm/v/ellmos-filecommander-mcp.svg)](https://www.npmjs.com/package/ellmos-filecommander-mcp)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)
[![FileCommander tests](https://github.com/ellmos-ai/ellmos-filecommander-mcp/actions/workflows/tests.yml/badge.svg)](https://github.com/ellmos-ai/ellmos-filecommander-mcp/actions/workflows/tests.yml)

A comprehensive **Model Context Protocol (MCP) server** that gives AI assistants full filesystem access, process management, interactive shell sessions, and async file search capabilities.

**46 tools** in a single server - everything an AI agent needs to interact with the local system.

**Discovery keywords:** local filesystem MCP server, safe delete MCP, Recycle Bin MCP server, process management MCP, interactive shell MCP, async file search for AI agents, cloud-lock-safe file operations, Markdown to PDF MCP, OCR MCP server, ZIP archive MCP.

**Registry status:** published on [npm](https://www.npmjs.com/package/ellmos-filecommander-mcp), indexed by [jsDelivr](https://www.jsdelivr.com/package/npm/ellmos-filecommander-mcp), visible on [LobeHub](https://lobehub.com/mcp/ellmos-ai-ellmos-filecommander-mcp), listed on [Glama](https://glama.ai/mcp/servers/eyurifgg4t), and prepared for the official MCP Registry via [`server.json`](server.json). Some third-party directories still show older 43-tool metadata, so the canonical README/npm metadata should remain the source of truth until their reindex catches up.

---

## Why FileCommander?

Most filesystem MCP servers only cover basic read/write operations. FileCommander goes further:

- **Safe Delete** - Moves files to Recycle Bin (Windows) or Trash (macOS/Linux) instead of permanent deletion
- **Interactive Sessions** - Start and interact with REPLs (Python, Node.js, shells) through the MCP protocol
- **Async Search** - Search large directory trees in the background while the AI continues working
- **Process Management** - List, start, and terminate system processes
- **String Replace** - Edit files by matching unique strings with context validation
- **Format Conversion** - Convert between JSON, CSV, INI, YAML, TOML, XML, and TOON
- **ZIP Archives** - Create, extract, and list ZIP archives
- **File Checksums** - SHA-256, MD5, SHA-1, SHA-512 hashing with compare
- **OCR** - Extract text from images (optional tesseract.js dependency)
- **Safety Mode** - Toggle to route all deletes through Recycle Bin / Trash
- **Markdown Export** - Convert Markdown to professional HTML/PDF with code blocks, tables, nested lists, blockquotes
- **Cloud-Lock Safe** - Automatic copy+delete fallback when cloud sync filters (OneDrive, Dropbox, Google Drive, iCloud) block rename operations
- **Cloud Lock Diagnosis** - Check whether a path is at risk of sync-filter conflicts before operating
- **Cross-platform** - Works on Windows, macOS, and Linux with platform-specific optimizations

---

## Installation

### Prerequisites

- [Node.js](https://nodejs.org/) 18 or higher
- npm

### Option 1: Install from NPM

```bash
npm install -g ellmos-filecommander-mcp
```

### Option 2: Install from Source

```bash
git clone https://github.com/ellmos-ai/ellmos-filecommander-mcp.git
cd ellmos-filecommander-mcp
npm install
npm run build
```

---

## Configuration

### Claude Desktop

Add to your `claude_desktop_config.json`:

**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

#### If installed globally via NPM:

```json
{
  "mcpServers": {
    "filecommander": {
      "command": "ellmos-filecommander"
    }
  }
}
```

#### If installed from source:

```json
{
  "mcpServers": {
    "filecommander": {
      "command": "node",
      "args": ["/absolute/path/to/filecommander-mcp/dist/index.js"]
    }
  }
}
```

Restart Claude Desktop after saving.

### Other MCP Clients

The server communicates via **stdio transport**. Point your MCP client to the `dist/index.js` entry point or the `ellmos-filecommander` binary.

---

## Tools Overview

### Filesystem Operations (14 tools)

| Tool | Description |
|------|-------------|
| `fc_read_file` | Read file contents with optional line limit |
| `fc_read_multiple_files` | Read up to 20 files in a single call |
| `fc_write_file` | Write/create/append to files |
| `fc_edit_file` | Line-based editing (replace, insert, delete lines) |
| `fc_str_replace` | Replace a unique string in a file with context validation |
| `fc_list_directory` | List directory contents (recursive, configurable depth) |
| `fc_create_directory` | Create directories (including parents) |
| `fc_delete_file` | Delete a file (permanent) |
| `fc_delete_directory` | Delete a directory (with optional recursive flag) |
| `fc_safe_delete` | Move to Recycle Bin / Trash (recoverable!) |
| `fc_move` | Move or rename files and directories (cloud-lock safe) |
| `fc_copy` | Copy files and directories |
| `fc_file_info` | Get detailed file metadata (size, dates, type) |
| `fc_search_files` | Synchronous file search with wildcard patterns |

### Async Search (5 tools)

| Tool | Description |
|------|-------------|
| `fc_start_search` | Start a background search (returns immediately) |
| `fc_get_search_results` | Retrieve results with pagination |
| `fc_stop_search` | Cancel a running search |
| `fc_list_searches` | List all active/completed searches |
| `fc_clear_search` | Remove completed searches from memory |

### Process Management (4 tools)

| Tool | Description |
|------|-------------|
| `fc_execute_command` | Execute a shell command (blocking, with timeout) |
| `fc_start_process` | Start a background process (non-blocking) |
| `fc_list_processes` | List running system processes |
| `fc_kill_process` | Terminate a process by PID or name |

### Interactive Sessions (5 tools)

| Tool | Description |
|------|-------------|
| `fc_start_session` | Start an interactive process (Python, Node, shell...) |
| `fc_read_output` | Read session output |
| `fc_send_input` | Send input to a running session |
| `fc_list_sessions` | List all sessions |
| `fc_close_session` | Terminate a session |

### File Maintenance & Repair (9 tools)

| Tool | Description |
|------|-------------|
| `fc_fix_json` | Repair broken JSON (BOM, trailing commas, comments, single quotes) |
| `fc_validate_json` | Validate JSON with detailed error position and context |
| `fc_cleanup_file` | Remove BOM, NUL bytes, trailing whitespace, normalize line endings |
| `fc_fix_encoding` | Fix Mojibake / double-encoded UTF-8 (27+ character patterns) |
| `fc_folder_diff` | Track directory changes with snapshots (new/modified/deleted) |
| `fc_batch_rename` | Pattern-based batch renaming (prefix/suffix, replace, auto-detect) |
| `fc_convert_format` | Convert between JSON, CSV, INI, YAML, TOML, XML, and TOON formats |
| `fc_detect_duplicates` | Find duplicate files using SHA-256 hashing |
| `fc_checksum` | File hashing (MD5, SHA-1, SHA-256, SHA-512) with optional compare |

### Archive (1 tool)

| Tool | Description |
|------|-------------|
| `fc_archive` | Create, extract, and list ZIP archives |

### OCR (1 tool)

| Tool | Description |
|------|-------------|
| `fc_ocr` | Extract text from images via tesseract.js (optional dependency) |

### Cloud Sync (1 tool)

| Tool | Description |
|------|-------------|
| `fc_check_cloud_lock` | Diagnose whether a path may be blocked by cloud sync filters (Windows) |

### System (2 tools)

| Tool | Description |
|------|-------------|
| `fc_get_time` | Get current system time with timezone info |
| `fc_set_safe_mode` | Toggle safe mode: all deletes go through Recycle Bin / Trash |

### Export (2 tools)

| Tool | Description |
|------|-------------|
| `fc_md_to_html` | Markdown to standalone HTML with CSS styling (headers, code blocks, tables, nested lists, blockquotes, images, checkboxes) |
| `fc_md_to_pdf` | Markdown to PDF via headless browser (Edge/Chrome). Falls back to HTML if no browser is available |

### Web (1 tool)

| Tool | Description |
|------|-------------|
| `fc_web_fetch` | Fetch a web page and return content by `mode`: extract (clean main text), raw (HTTP body), links, forms, or headers. Read-only network tool; SSRF guard blocks internal/private targets by default. |

**Total: 46 tools**

---

## Comparison with Alternatives

| Feature | FileCommander | [Desktop Commander](https://github.com/wonderwhy-er/DesktopCommanderMCP) | [Official Filesystem](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem) |
|---------|:---:|:---:|:---:|
| File read/write/copy/move | 14 tools | Yes | Yes |
| Safe delete (Recycle Bin) | Yes | No | No |
| Async background search | 5 tools | No | No |
| Interactive sessions (REPL) | 5 tools | Yes | No |
| Process management | 4 tools | Yes | No |
| Shell command execution | Yes | Yes | No |
| String replace with validation | Yes | Yes | No |
| Line-based file editing | Yes | No | No |
| JSON repair & validation | 2 tools | No | No |
| Encoding fix (Mojibake) | Yes | No | No |
| Duplicate detection (SHA-256) | Yes | No | No |
| Folder diff / change tracking | Yes | No | No |
| Batch rename (pattern-based) | Yes | No | No |
| Format conversion (JSON/CSV/INI/YAML/TOML/XML/TOON) | Yes | No | No |
| ZIP archive (create/extract/list) | Yes | No | No |
| File checksums (SHA-256/MD5) | Yes | No | No |
| OCR (image to text) | Optional | No | No |
| Safety mode (delete → Recycle Bin) | Yes | No | No |
| Path allowlist / sandboxing | No | No | Yes |
| Excel / PDF support | PDF (via browser) | Yes | No |
| HTTP transport