io.github.ellmos-ai/ellmos-filecommander-mcp (MCP) Server

This MCP server provides filesystem-related capabilities, including file handling plus support for processes and sessions. It also includes asynchronous search, OCR, archive operations, and a “safe delete” capability. Overall, it is designed to interact with local filesystem content and related workflows.

🛠️ Key Features

Filesystem access
Processes and sessions support
Async search
OCR
Archive operations
Safe delete

🚀 Use Cases

Searching filesystem content asynchronously
Performing OCR on supported inputs
Working with archived files
Deleting files using safer delete semantics
Managing or interacting with filesystem-associated processes and sessions

⚡ Developer Benefits

Consolidated filesystem tooling through an MCP server
Enables async search workflows and OCR within the same interface
Supports archive handling and safer deletion operations

⚠️ Limitations

No additional tooling details (e.g., specific tool count or supported formats) were provided.

FileCommander banner

ellmos FileCommander MCP Server

🇩🇪 Deutsche Version

Part of the ellmos-ai family.

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, indexed by jsDelivr, visible on LobeHub, listed on Glama, and prepared for the official MCP Registry via 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.

NOTE

For AI Agents & LLM Integrations: FileCommander provides 46 specialized tools accessible via standard stdio transport. All tool names use the fc_ prefix to prevent namespace collisions. For LLMs, compact context and schema overviews are available in llms.txt and server.json.

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

System Architecture

flowchart TD
    subgraph Client["MCP Client Layer"]
        Claude["Claude Desktop / Claude Code"]
        Custom["Custom LLM Agents / Frameworks"]
    end

    subgraph Transport["Transport Layer"]
        Stdio["Stdio Transport (JSON-RPC)"]
    end

    subgraph Core["ellmos FileCommander Engine (46 Tools)"]
        FS["Filesystem & Cloud-Lock Guard\n(14 tools: read, write, edit, safe-delete, cloud-lock safe)"]
        Search["Async Search Engine\n(5 tools: start, get, stop, list, clear)"]
        Proc["Process & REPL Sessions\n(9 tools: exec, background proc, interactive REPLs)"]
        Repair["Repair & Format Converter\n(9 tools: JSON fix, Mojibake fix, duplicates, format convert)"]
        Export["Export & Web Scraper\n(3 tools: Markdown->HTML/PDF, web_fetch)"]
        Sys["System & Utilities\n(6 tools: OCR, ZIP, checksums, safe-mode, time)"]
    end

    Client -->|JSON-RPC| Stdio
    Stdio --> Core
    Core --> FS
    Core --> Search
    Core --> Proc
    Core --> Repair
    Core --> Export
    Core --> Sys

Installation

Prerequisites

Node.js 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	Official 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	No	No	No
Markdown to HTML/PDF export	Yes	No	No
Total tools	46	~15	~11
Servers needed	1	1	+ extra for processes

Key differentiators:

Only MCP server with recoverable delete (Recycle Bin / Trash)
Only MCP server with async background search with pagination
Built-in JSON repair, encoding fix, and duplicate detection
Only MCP server with cloud-lock-safe file operations (automatic copy+delete fallback)
Most comprehensive single-server solution (46 tools)
Built-in safety mode to prevent accidental permanent deletion

Tool Prefix

All tools use the fc_ prefix (FileCommander) to avoid conflicts with other MCP servers.

Discoverability

FileCommander is designed to be discoverable by both people and AI agents:

package.json exposes the official mcpName (io.github.ellmos-ai/ellmos-filecommander-mcp) and MCP-specific npm keywords.
server.json follows the official MCP Registry schema and points to the npm package.
glama.json provides MCP-directory metadata for Glama-compatible indexes.
llms.txt gives compact context for LLMs, agent catalogs, and documentation crawlers.

Primary search terms: ellmos-filecommander-mcp, FileCommander MCP, filesystem MCP server, safe delete MCP, async file search MCP, process management MCP, Markdown PDF MCP.

External discovery notes: npm and jsDelivr already show the current package metadata. LobeHub indexes the GitHub repo as an MCP server. Some secondary MCP directories still cache older 43-tool descriptions; use the package description and this README as the canonical 46-tool reference.

Security

This server has full filesystem access with the running user's permissions.

See SECURITY.md for detailed security information and recommendations.

Key points:

fc_execute_command runs arbitrary shell commands
fc_delete_* tools perform permanent deletion by default (use fc_safe_delete or enable safe mode via fc_set_safe_mode to route all deletes through Recycle Bin / Trash)
No built-in sandboxing - security is delegated to the MCP client layer
Designed for local use via stdio transport only

Development

bash

# Install dependencies
npm install

# Watch mode (auto-rebuild on changes)
npm run dev

# One-time build
npm run build

# Start the server
npm start

# Run test suite
npm test

Testing

The project includes a comprehensive test suite with 154 tests covering filesystem operations, format conversion, encoding repair, archive handling, duplicate detection, i18n language packs, and more.

bash

npm test              # Run all tests
npx vitest run        # Same as above
npx vitest --watch    # Watch mode

Tests are verified on Windows, macOS, and Linux. Pushes and pull requests run CI on Node.js 20, 22, and 24 with npm ci, TypeScript build, Vitest, and an npm package dry-run.

See CONTRIBUTING.md for contribution guidelines.

Changelog

See CHANGELOG.md for the full version history.

License

MIT - Lukas Geiger (ellmos-ai)

History

This project was originally developed as BACH FileCommander (bach-filecommander-mcp). It has been renamed to ellmos FileCommander (ellmos-filecommander-mcp) as part of the ellmos-ai organization.

The legacy package name bach-filecommander-mcp is deprecated. Please use ellmos-filecommander-mcp instead:

bash

npm uninstall -g bach-filecommander-mcp
npm install -g ellmos-filecommander-mcp

ellmos-ai Ecosystem

This MCP server is part of the ellmos-ai ecosystem — AI infrastructure, MCP servers, and intelligent tools.

MCP Server Family

Server	Tools	Focus	npm
FileCommander	46	Filesystem, process management, interactive sessions, cloud-lock-safe operations	`ellmos-filecommander-mcp`
CodeCommander	22	Code analysis, JSON repair, imports, diffs, regex	`ellmos-codecommander-mcp`
Clatcher	12	File repair, format conversion, batch operations	`ellmos-clatcher-mcp`
n8n Manager	18	n8n workflow management via AI assistants	`n8n-manager-mcp`
ControlCenter	20	MCP stack discovery, profile management, control plane	`ellmos-controlcenter-mcp`
Homebase	45	Local-first LLM memory, knowledge, state, routing, swarm orchestration	`ellmos-homebase-mcp` (alpha)
ServerCommander	8	Server operations: health checks, log analysis, deploy dry-runs, mail diagnostics	`ellmos-servercommander-mcp` (alpha)
Blender Use	3	Headless Blender asset QA and FBX reimport verification	`ellmos-blender-use-mcp` (alpha)
Open Compute	10	Model-agnostic computer use: capture, safety-gated actions, Windows UIA	`open-compute-mcp` (alpha)

AI Infrastructure

Project	Description
BACH	Local-first text-based OS for LLM agents — 113+ handlers, 550+ tools, SQLite memory
open-compute	Model-agnostic computer-use core powering Open Compute MCP
clutch	Provider-neutral LLM orchestration with auto-routing and budget tracking
rinnsal	Lightweight agent memory, connectors, and automation infrastructure
ellmos-stack	Self-hosted AI research stack (Ollama + n8n + Rinnsal + KnowledgeDigest)
MarbleRun	Autonomous agent chain framework for Claude Code
gardener	Minimalist database-driven LLM OS prototype (4 functions, 1 table)
ellmos-tests	Testing framework for LLM operating systems (7 dimensions)

Desktop Software

Our partner organization open-bricks bundles AI-native desktop applications — a modern, open-source software suite built for the age of AI. Categories include file management, document tools, developer utilities, and more.

Haftung / Liability

Dieses Projekt ist eine unentgeltliche Open-Source-Schenkung im Sinne der §§ 516 ff. BGB. Die Haftung des Urhebers ist gemäß § 521 BGB auf Vorsatz und grobe Fahrlässigkeit beschränkt. Ergänzend gilt der Haftungsausschluss der MIT-Lizenz.

Nutzung auf eigenes Risiko. Keine Wartungszusage, keine Verfügbarkeitsgarantie, keine Gewähr für Fehlerfreiheit oder Eignung für einen bestimmten Zweck.

This project is an unpaid open-source donation. Liability is limited to intent and gross negligence (§ 521 German Civil Code). The MIT license disclaimer also applies. Use at your own risk. No warranty, no maintenance guarantee, no fitness-for-purpose assumed.

io.github.ellmos-ai/ellmos-filecommander-mcp (MCP) Server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

ellmos FileCommander MCP Server

Why FileCommander?

System Architecture

Installation

Prerequisites

Option 1: Install from NPM

Option 2: Install from Source

Configuration

Claude Desktop

If installed globally via NPM:

If installed from source:

Other MCP Clients

Tools Overview

Filesystem Operations (14 tools)

Async Search (5 tools)

Process Management (4 tools)

Interactive Sessions (5 tools)

File Maintenance & Repair (9 tools)

Archive (1 tool)

OCR (1 tool)

Cloud Sync (1 tool)

System (2 tools)

Export (2 tools)

Web (1 tool)

Comparison with Alternatives

Tool Prefix

Discoverability

Security

Development

Testing

Changelog

License

History

ellmos-ai Ecosystem

MCP Server Family

AI Infrastructure

Desktop Software

Haftung / Liability

Install