ellmos FileCommander

Official

by ellmos-ai · TypeScript

Filesystem MCP server: files, processes, sessions, async search, OCR, archives, safe delete.

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

The ellmos FileCommander MCP Server is a Model Context Protocol (MCP) server focused on filesystem operations. It supports working with files and directories, process management, and sessions. It provides async search, OCR, and archive handling, including safe delete, and includes export support for markdown and PDF.

🛠️ Key Features

Filesystem file and process management
Sessions support
Async search
OCR
Archives handling
Safe delete
Markdown export
PDF export

🚀 Use Cases

Search and retrieve information from local files asynchronously
Extract text from documents using OCR
Manage and safely delete files
Handle archived files and export results to Markdown or PDF
Coordinate filesystem-related workflows that involve processes and sessions

⚡ Developer Benefits

MCP server with filesystem, process-management, and session concepts
Async search for non-blocking retrieval
Export outputs to markdown and PDF
Includes cross-platform and local-first oriented tooling per topics

⚠️ Limitations

Scope appears limited to filesystem-centered capabilities (files, processes, sessions, search, OCR, archives, safe delete, exports).

Topics

ai-toolsclaudefilesystemmcpmcp-servermodel-context-protocolprocess-managementagent-frameworkasync-searchcross-platformllmllm-agentslocal-firstshellmarkdown-exportmcp-registrypdf-exportsafe-deletefile-managementcloud-lock

README.md43 KBView on GitHub

FileCommander banner

ellmos FileCommander MCP Server

🇩🇪 Deutsche Version

Part of the ellmos-ai family.

Tests

Quick Navigation:

Overview | 2. System Architecture | 3. End-to-End Execution Lifecycle | 4. Core Capabilities & Safety Invariants | 5. Target Personas & Discoverability | 6. Installation & Prerequisites | 7. Configuration & Client Setup | 8. Tools Overview (50 Tools) | 9. Comparative Matrix & Alternatives | 10. Tool Prefix & Naming Convention | 11. Governance & Runtime Invariants | 12. Security Architecture & Tool Risks | 13. Testing, Quality Gates & Verification | 14. Changelog & Versioning | 15. Level 1 SBOM & Third-Party Licenses | 16. History & Evolution | 17. ellmos-ai Ecosystem & Partner Matrix | 18. Statutory Notice (§ 521 BGB) & Liability Disclaimer

| Direct References: 🛡️ Security Policy • ⚖️ Third-Party Licenses • 📄 Plain Text SBOM • 📜 Marketing Log • 🤖 LLM Context (llms.txt) • 📋 Canonical Notice |

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

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

Discovery keywords: local filesystem MCP server, multi-file content search MCP, 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 50 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.

Overview & 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
Explicit Content Search - Search literal text or regex across a bounded list of files without recursion or glob expansion
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 - MD5, SHA-1, SHA-256, SHA-384, and 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 (50 Tools)"]
        FS["Filesystem Engine\n(15 tools: read, bounded preview, write, edit, safe-delete, cloud-lock safe)"]
        Search["Search Engine\n(6 tools: explicit content search plus 5 async filename-search tools)"]
        Proc["Process & REPL Sessions\n(10 tools: exec, default-app opening, background proc, interactive REPLs)"]
        Repair["Repair & Format Converter\n(9 tools: JSON fix, Mojibake fix, duplicates, format convert, checksum)"]
        Export["Export & Web Fetch\n(3 tools: Markdown->HTML/PDF, web_fetch)"]
        Sys["System, Utilities & i18n\n(7 tools: OCR, ZIP, cloud-lock check, safe-mode, time, language set/get)"]
    end

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

End-to-End Execution Lifecycle

sequenceDiagram
    autonumber
    participant AI as AI Assistant (Client)
    participant FC as FileCommander Engine
    participant FS as Host Filesystem
    participant Trash as Recycle Bin / Trash
    participant Cloud as Cloud Sync Filter

    Note over AI,FC: 1. Safe Deletion & Recovery Protection
    AI->>FC: fc_delete_file / fc_safe_delete(targetPath)
    alt Safety Mode Active or fc_safe_delete invoked
        FC->>Trash: Move item to Recycle Bin / Trash
        Trash-->>FC: Moved safely (recoverable)
        FC-->>AI: Success (item preserved in Trash/Recycle Bin)
    else Permanent Unlink requested
        FC->>FS: Direct unlink
        FS-->>FC: Removed permanently
        FC-->>AI: Success
    end

    Note over AI,Cloud: 2. Resilient Cloud-Lock Handling (OneDrive/Dropbox)
    AI->>FC: fc_move(sourcePath, destPath)
    alt Cloud Filter Locks Destination
        FC->>Cloud: Attempt standard rename
        Cloud-->>FC: EPERM / EBUSY (Cloud Filter Error)
        FC->>FS: Fallback: copyFileSync + SHA-256 verify
        FC->>FS: unlinkSync source
        FC-->>AI: Move succeeded via resilient fallback
    else Local Native Filesystem
        FC->>FS: Rename (atomic)
        FS-->>FC: Done
        FC-->>AI: Move succeeded
    end

Core Capabilities & Safety Invariants

Capability / Invariant	Guarantee & Implementation Details	Security & Operational Benefit
Local stdio & explicit egress	The MCP transport is local stdio, with no telemetry and no automatic network egress. `fc_web_fetch` makes outbound HTTP(S) requests only when a client explicitly invokes it; private targets are blocked by default unless `allow_private` is enabled.	Makes the network boundary visible to clients while retaining a local, port-free server transport.
Safe Deletion & Trash Protection	`fc_safe_delete` moves items to Windows Recycle Bin / macOS Trash / Linux FreeDesktop Trash. `fc_set_safe_mode` routes all deletes safely.	Prevents irreversible data loss from accidental recursive or bulk deletions.
Cloud-Lock Resilient Move (`fc_move`)	Automatic detection of cloud sync filters (OneDrive, Dropbox, iCloud reparse points) with seamless copy+verify+delete fallback.	Eliminates `EPERM` / `EBUSY` failures during automated agent operations in sync directories.
Cloud-Lock Diagnosis (`fc_check_cloud_lock`)	Read-only report of static cloud-path context plus target existence/type; Cloud Files hydration and process handles are explicitly reported as not checked when unavailable.	Agents can distinguish static OneDrive risk from an actual detected rename lock.
Bounded Multi-File Content Search	`fc_search_content` strictly caps inputs (max 50 explicit files, 10 MB per file, 200 matches, 200k chars) without glob recursion.	Prevents out-of-memory errors and catastrophic CPU lockups during large repository searches.
Automated Secret & Token Redaction	Content search excerpts automatically mask common API keys, bearer tokens, AWS credentials, and authorization headers.	Prevents LLM context contamination and accidental credential leakage in prompt history.
Interactive REPL & Session Isolation	Stateful interactive sessions (`fc_start_session`, `fc_send_input`, `fc_read_output`) for Python, Node.js, bash, and PowerShell with bounded buffers.	Allows multi-turn REPL debugging without unconstrained background process buildup.
Lossless Multi-Format Engine	Declarative conversion (`fc_convert_format`) across 7 structured formats (JSON, YAML, TOML, XML, CSV, INI, TOON).	Clean data normalization across heterogeneous configuration formats without data loss.
Mojibake & File Repair Engine	`fc_fix_encoding`, `fc_fix_json`, and `fc_cleanup_file` repair broken UTF-8 encoding (27+ patterns), malformed JSON syntax, BOMs, and NUL bytes.	Self-healing pipelines for corrupted files generated across divergent OS platforms.
Unprivileged Non-Elevation Execution	Designed and verified to run in standard unprivileged user-mode. Never requires administrative or root privileges.	Minimal attack surface; adheres to the principle of least privilege.
Six-language Runtime i18n Engine	Dynamic language switching and introspection (`fc_set_language`, `fc_get_language`) for German (`de`), English (`en`), Spanish (`es`), Chinese (`zh`), Japanese (`ja`), and Russian (`ru`).	Native multilingual developer experience and localized error reporting.
Multi-OS Verified Matrix	Tested across Windows, Ubuntu Linux, and macOS on Node.js 20, 22, and 24 with 292 automated assertions.	Continuous cross-platform parity and reliability.

Target Personas & Discoverability

FileCommander is purpose-built and validated for four core developer, agentic, and operations personas:

[PERSONA-01] Autonomous AI Coding Agents & LLM Swarms

Profile: Multi-agent swarms and standalone agentic runtimes (Claude Code, Antigravity/Gemini, OpenAI Codex, AutoGen, CrewAI) executing recursive code editing, project refactoring, and directory audits.
Key Operational Pain Points: Rapid context window bloat caused by reading multi-megabyte files, unhandled process crashes from locked files (EPERM/EBUSY) in cloud-synced folders, and unrecoverable repository corruption from accidental rm -rf cleanup routines.
FileCommander Solution:
- fc_preview_file: Metadata-first inspection with strict 1 MiB inline content ceiling preventing LLM context blowout.
- fc_search_content: Bounded multi-file search (max 50 files, 10 MB per file, 200 matches) with automatic secret/token redaction.
- fc_safe_delete & fc_set_safe_mode: Preserves deleted files in OS Recycle Bin / Trash for zero-risk file operations.
- fc_move & fc_check_cloud_lock: Automatic copy + SHA-256 verify + unlink fallback on file locks, preventing agent failure.

[PERSONA-02] DevOps, Toolchain & Multi-Host Automation Engineers

Profile: Systems and automation engineers constructing cross-platform CLI tools, CI/CD validation pipelines, and multi-machine sync scripts across Windows, Linux, and macOS.
Key Operational Pain Points: Heterogeneous operating system semantics (Windows backslashes vs POSIX slashes, line-ending corruption, shell-specific syntax), zombie child processes, and file locking in shared OneDrive/Dropbox workspaces.
FileCommander Solution:
- Cross-platform unified tool semantics across Windows, Linux, and macOS.
- Stateful interactive REPL sessions (fc_start_session, fc_send_input, fc_read_output) with bounded circular ring buffers.
- Batch file renaming (fc_batch_rename) and background directory search (fc_start_search, fc_get_search_results).
- Process lifecycle management (fc_execute_command, fc_start_process, fc_kill_process) without process leaks.

[PERSONA-03] SecOps, Governance & Compliance Officers

Profile: Security officers, compliance auditors, and privacy teams overseeing AI tool integrations in enterprise and production environments.
Key Operational Pain Points: Undisclosed background telemetry beacons, unvetted network access from local plugins, credential/token leakage into model training or prompt histories, and unprivileged user privilege escalation.
FileCommander Solution:
- Local stdio transport with strictly zero telemetry and zero open network listening ports.
- Explicit outbound network egress strictly restricted to caller-invoked fc_web_fetch (internal/private IPs blocked by default).
- Automated secret and bearer token masking in search excerpts (INV-MASK-06).
- Strict unprivileged user execution (INV-PROC-09) and binding 48-hour vulnerability response SLA (security@open-bricks.org, security@ellmos.ai).

[PERSONA-04] Enterprise Platform Architects & Data Pipeline Developers

Profile: Solutions architects and data engineers integrating local files, normalizing heterogeneous configuration formats, validating cryptographic hashes, and generating reports.
Key Operational Pain Points: MCP server sprawl requiring 4-6 disparate single-purpose servers, corrupted UTF-8 byte sequences (Mojibake) across tools, and bespoke parsing scripts.
FileCommander Solution:
- Comprehensive 50-tool single-server deployment eliminating multi-server sprawl and process overhead.
- Lossless declarative conversion across 7 structured formats (fc_convert_format: JSON, YAML, TOML, XML, CSV, INI, TOON).
- Built-in file repair engines (fc_fix_encoding, fc_fix_json, fc_cleanup_file) for self-healing pipelines.
- Cryptographic checksums (fc_checksum: SHA-256, SHA-512, MD5, SHA-1) and Markdown to PDF/HTML rendering (fc_md_to_pdf, fc_md_to_html).

High-Intent Search Queries & Discoverability Vectors

Primary Search Queries: ellmos-filecommander-mcp, FileCommander MCP, filesystem MCP server, multi-file content search MCP, safe delete MCP, async file search MCP, process management MCP, Markdown PDF MCP.
Machine-Readable Metadata: Structured context for AI agents is maintained in llms.txt, server.json, and glama.json.
Compliance & Attribution: Validated against THIRD_PARTY_LICENSES.md and NOTICE.

Installation

Prerequisites

Node.js 20 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 (15 tools)

Tool	Description
`fc_read_file`	Read file contents with optional line limit
`fc_preview_file`	Inspect MIME type and size first, then explicitly request bounded inline MCP content
`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

fc_preview_file is the remote/headless fallback for local files. Its default call returns structured metadata only: resolved path, file:// URI, MIME type, byte size, preview kind, fixed 1 MiB limit, and the exact follow-up call. Content is read only after include_content=true. Eligible text and raster images use standard MCP text/image content blocks; PDFs use a bounded embedded resource. Files above 1 MiB and unsupported types remain metadata-only and are never read or Base64-encoded by the preview path.

Content Search (1 tool)

Tool	Description
`fc_search_content`	Read-only literal or regex search within an explicit ordered list of files, with case, context, global, and per-file limits

fc_search_content never expands globs, traverses directories, or recursively discovers files. It accepts at most 50 explicit UTF-8 text files, skips binary and files over 10 MB, and returns deterministic JSON. Matches are limited to 200 globally and 100 per file, context to 10 lines, excerpts to 500 characters, and serialized output to 200,000 characters. Missing, cloud-only, permission, encoding, binary, and size failures are reported per file so readable files still produce results. Common secret formats are redacted from excerpts.

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 (5 tools)

Tool	Description
`fc_execute_command`	Execute a shell command (blocking, with timeout)
`fc_start_process`	Start a background process (non-blocking)
`fc_open_path`	Validate and open an existing local file or directory with the OS default application
`fc_list_processes`	List running system processes
`fc_kill_process`	Terminate a process by PID or name

fc_open_path accepts only an existing file or directory and sends it to a fixed native default-handler launcher. Its structured result reports launcher_accepted=true|false, always reports user_visible="unknown", and identifies a machine-readable fallback: fc_preview_file with metadata-only arguments for files or fc_list_directory for directories. Launcher acceptance never claims that a GUI became visible. fc_start_process instead lets the caller choose an executable and arguments. fc_execute_command accepts an arbitrary shell command: Node's default shell is used for ordinary commands (COMSPEC/cmd.exe on Windows), while FileCommander's Windows special-character path can route through Windows PowerShell.

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-384, 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`	Report static cloud-sync context and target state; never claim an active lock without evidence (Windows)

System (4 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
`fc_set_language`	Set the runtime language (`de`, `en`, `es`, `zh`, `ja`, or `ru`)
`fc_get_language`	Read the active runtime language and all supported language codes

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: 50 tools

Comparative Matrix & Alternatives

FileCommander combines filesystem manipulation, bounded search, process control, data repair, format conversion, and document rendering into a single unified MCP interface. Below is an architectural comparison against standard alternatives across 10 key operational dimensions:

Operational Dimension	ellmos FileCommander MCP (50 Tools)	Official Filesystem MCP (`@modelcontextprotocol/server-filesystem`)	Desktop Commander MCP	Direct Host Shell (`bash` / PowerShell)	Ad-Hoc Scripts & Cloud APIs
Tool Breadth & Scope `[INV-PROC-09]`	50 unified tools across 6 domains	~11 basic file I/O tools	~15 tools (file + process)	Unconstrained CLI commands	Fragmented bespoke scripts
Safe Deletion & Recovery `[INV-SAFE-02]`	Native OS Recycle Bin / Trash (`fc_safe_delete`, Safety Mode)	Permanent deletion only (`unlink`)	Permanent deletion only	Irreversible `rm -rf` / `Remove-Item`	Custom trash implementations
Cloud-Lock & Sync Resilience `[INV-LOCK-03]`	Automatic fallback (copy + SHA-256 verify + unlink on EPERM/EBUSY)	Fails on locked files / reparse points	Fails on locked files	Fails or blocks indefinitely	Sync collision / conflict copies
Bounded Search & Secret Redaction `[INV-SRCH-05 / INV-MASK-06]`	Bounded search (max 50 files, 10 MB, auto API token redaction)	Directory walk only (no content regex)	Unbounded regex search	Unbounded `grep` (leaks secrets in context)	Custom regex without redaction
Async Long-Running Search `[INV-SRCH-05]`	Token-paginated background scans (`fc_start_search`)	Synchronous only (blocks agent)	Synchronous only	Background job control (`&`)	Polling loops / slow network calls
Interactive REPL & Session Control `[INV-REPL-08]`	Stateful REPLs (Node, Python, Shell) with circular buffers	Not supported	Basic terminal sessions	Raw subprocesses (zombie process risk)	Complex IPC piping
Self-Healing & Data Repair `[INV-DIAG-04]`	Built-in Mojibake fix (27+ patterns) & JSON repair	Not supported	Not supported	Manual `iconv` / `sed` pipeline	Custom error recovery code
Multi-Format Transformation `[INV-PREV-07]`	Declarative conversion (JSON, YAML, TOML, XML, CSV, INI, TOON)	Not supported	Not supported	Requires external `jq` / `yq` / `xmlstarlet`	Third-party Python libraries
Document & Archive Utilities `[INV-PREV-07]`	Built-in ZIP lifecycle, OCR (Tesseract), Markdown to HTML/PDF	Not supported	Excel/PDF via desktop app	Requires `pandoc`, `zip`, `tesseract`	Fragmented utility dependencies
Governance & Security SLAs `[INV-LOCAL-01 / INV-SLA-10]`	Local stdio, zero telemetry, explicit egress, binding 48h SLA	Standard stdio, community SLA	Stdio, unvetted telemetry/logs	Unrestricted elevation & script injection risk	Ad-hoc SaaS cloud exposure

Key differentiators:

Only MCP server with recoverable delete (Recycle Bin / Trash) and global Safety Mode
Only MCP server with async background search with pagination and token management
Only MCP server with automated secret & bearer token redaction in search snippets
Built-in JSON repair, Mojibake encoding fix, and duplicate detection
Built-in cloud-lock-safe file operations with automatic copy+verify+delete fallback
Most comprehensive single-server solution (50 tools) eliminating multi-server sprawl

Tool Prefix

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

Governance & Runtime Invariants

The server enforces 10 strict runtime invariants guaranteeing safety, predictability, and least privilege:

Invariant ID	Name	Guarantee & Implementation Details	Operational Safety Benefit
INV-LOCAL-01	Local stdio & explicit egress	Local stdio transport, zero telemetry, no open listening ports. Outbound HTTP(S) requests strictly occur via explicit client calls to `fc_web_fetch`.	Zero unauthorized background network leakage; local-first isolation.
INV-SAFE-02	Safe Deletion & Trash Protection	`fc_safe_delete` and global `fc_set_safe_mode` route file and directory deletions through OS Recycle Bin (Windows) / Trash (macOS/Linux).	Eliminates irreversible accidental data loss from AI agent actions.
INV-LOCK-03	Cloud-Lock Resilient Move	`fc_move` automatically executes copy + SHA-256 verify + source unlink fallback when sync filters (OneDrive, Dropbox, iCloud) cause EPERM/EBUSY.	Guarantees file operations succeed reliably inside cloud-synchronized workspaces.
INV-DIAG-04	Cloud-Lock Diagnosis	`fc_check_cloud_lock` provides read-only static path inspection and reparse point detection without mutating filesystem state.	Enables agents to assess sync conflict risks before performing modifications.
INV-SRCH-05	Bounded Multi-File Content Search	`fc_search_content` strictly caps inputs (max 50 explicit files, 10 MB per file, 200 matches, 200k chars) without glob recursion.	Prevents out-of-memory crashes and unconstrained CPU consumption.
INV-MASK-06	Automated Secret & Token Redaction	Content search excerpts automatically detect and mask API keys, bearer tokens, AWS credentials, and authorization headers.	Protects credentials from prompt leakage and context contamination.
INV-PREV-07	Bounded Inline Preview & Safe Open	`fc_preview_file` is metadata-first with a strict 1 MiB inline content ceiling; `fc_open_path` invokes default application via shell-safe OS launchers.	Safe inspection of remote and local files without UI freeze or payload bloat.
INV-REPL-08	Interactive REPL & Session Isolation	Stateful interactive sessions (`fc_start_session`, `fc_send_input`, `fc_read_output`) employ bounded circular ring buffers.	Enables multi-turn REPL debugging while preventing zombie process buildup.
INV-PROC-09	Unprivileged Non-Elevation Execution	Executes entirely in standard unprivileged user-mode; never requests or requires administrative elevation or root rights.	Minimal attack surface; adheres strictly to the principle of least privilege.
INV-SLA-10	48h Security Response & 5-Day Triage SLA	Formal vulnerability commitment with multi-channel contacts (`security@open-bricks.org`, `security@ellmos.ai`).	Predictable, enterprise-ready incident response and triage lifecycle.

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_open_path invokes the operating system's associated application for a caller-selected existing path; that application runs with the user's permissions
fc_open_path reports launcher acceptance separately from the invariant user_visible="unknown"; fc_preview_file is the metadata-first remote fallback with an explicit 1 MiB inline-content boundary
fc_start_session starts an arbitrary interactive command, and subsequent fc_send_input calls can execute additional actions
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)
Safe mode protects only fc_delete_file and fc_delete_directory; it does not sandbox commands or interactive sessions
The server transport is local stdio and emits no telemetry, but an explicit fc_web_fetch call performs outbound HTTP(S) access
No built-in sandboxing - security is delegated to the MCP client layer

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 232 Vitest tests plus 71 standalone i18n checks (303 total) covering filesystem operations, metadata-first inline preview, bounded content search, native default-handler launching, format conversion, encoding repair, archive handling, duplicate detection, language packs, tool annotations, real stdio behavior, and security boundaries.

bash

npm test              # Run all tests
node test-i18n.mjs    # Run standalone i18n checks
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 & Legal Attribution

MIT - Lukas Geiger (ellmos-ai). See NOTICE for open-bricks umbrella attribution, THIRD_PARTY_LICENSES.md for Level 1 SBOM, and THIRD_PARTY_LICENSES.txt for plain-text SBOM.

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	50	Filesystem, bounded inline preview, content search, default-app opening, 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	19	n8n workflow management via AI assistants	`n8n-manager-mcp`
ControlCenter	31	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	5	Headless Blender asset QA and FBX reimport verification	`ellmos-blender-use-mcp` (alpha)
Open Compute	16	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 & Sibling Applications

Our partner organization open-bricks and its line organizations provide AI-native desktop applications and developer utilities:

Application	Category	Organization	Focus
ProFiler	File Management	file-bricks	High-speed dual-pane file manager with AI integration
ExplorerPro	File Exploration	file-bricks	Smart file explorer with semantic filters & preview
WinStorePackager	Packaging	file-bricks	MSIX & Store packaging for Windows desktop applications
SoftwareCenter	App Store	file-bricks	Centralized desktop package management & distribution
SQLiteViewer	Database Tool	file-bricks	Lightweight SQLite exploration & querying
DokuZen	Markdown Suite	doc-bricks	Markdown editor, PDF export & document conversion
MediaBrain	Document / Media	doc-bricks	Audio/video transcription, metadata extraction & cataloging
UniversalInvoiceMail	Document / Mail	doc-bricks	Automated invoice parsing, PDF extraction & mail routing
DevCenter	Developer Suite	dev-bricks	Integrated developer toolbox, code analyzers & generators
CodeBox	Code Editor	dev-bricks	Multi-language code editor with LLM augmentation
safe-start-for-codex	Security & Audit	dev-bricks	Hardened runtime environment & pre-flight checker for Codex
automation-master	Task Automation	dev-bricks	High-reliability background automation runner & scheduler

Haftung / Liability

Dieses Projekt ist eine unentgeltliche Open-Source-Schenkung im Sinne der §§ 516 ff. BGB (Gefälligkeitsrecht). Die Haftung des Urhebers und der Mitwirkenden 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.

Sicherheitsrelevante Vorfälle und Schwachstellen werden über das verbindliche 48-Stunden-SLA unter security@open-bricks.org und security@ellmos.ai entgegengenommen und innerhalb von 5 Werktagen triagiert.

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

Security incidents and vulnerabilities are handled under a binding 48-hour response SLA via security@open-bricks.org and security@ellmos.ai with formal triage within 5 business days.

Install

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "ellmos-filecommander-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "ellmos-filecommander-mcp@1.9.3"
      ]
    }
  }
}

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

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

ellmos FileCommander MCP Server

Overview & Why FileCommander?

System Architecture

End-to-End Execution Lifecycle

Core Capabilities & Safety Invariants

Target Personas & Discoverability

[PERSONA-01] Autonomous AI Coding Agents & LLM Swarms

[PERSONA-02] DevOps, Toolchain & Multi-Host Automation Engineers

[PERSONA-03] SecOps, Governance & Compliance Officers

[PERSONA-04] Enterprise Platform Architects & Data Pipeline Developers

High-Intent Search Queries & Discoverability Vectors

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 (15 tools)

Content Search (1 tool)

Async Search (5 tools)

Process Management (5 tools)

Interactive Sessions (5 tools)

File Maintenance & Repair (9 tools)

Archive (1 tool)

OCR (1 tool)

Cloud Sync (1 tool)

System (4 tools)

Export (2 tools)

Web (1 tool)

Comparative Matrix & Alternatives

Tool Prefix

Governance & Runtime Invariants

Security

Development

Testing

Changelog

License & Legal Attribution

History

ellmos-ai Ecosystem

MCP Server Family

AI Infrastructure

Desktop Software & Sibling Applications

Haftung / Liability

Install

Related servers