BACH FileCommander

[FileCommander banner]

ellmos FileCommander MCP Server

English | Deutsch | Español | 简体中文 | 日本語 | Русский | Français | हिन्दी | العربية | বাংলা | Português

The README navigation lists the documentation languages available in this repository. FileCommander runtime messages and formatted responses support German (de), English (en), Spanish (es), Chinese (zh), Japanese (ja), Russian (ru), French (fr), Hindi (hi), Arabic (ar), Bengali (bn), and Portuguese (pt). This runtime list is separate from README translation availability. It covers generated runtime messages and formatted tool responses; MCP tool titles, discovery descriptions, and schema descriptions remain static English. Set FC_LANGUAGE to one of the supported codes before starting the server, or call fc_set_language during an active MCP session. fc_get_language reports the active language and all eleven supported codes. Unset or unsupported FC_LANGUAGE values fall back to German (de). Date and time formatting follows the active locale.

Part of the ellmos-ai family.

[License: MIT] [CI] [npm version] [Node.js] [MCP Tools] [Tests] [Security: Explicit Egress] [Security: 48h SLA] [Safe Delete] [Attribution: NOTICE] [Unprivileged RunAsInvoker] [Third-Party Audited] [Level 1 SBOM: Plain Text] [ellmos-ai] [open-bricks] [Discovery: llms.txt] [Last-Checked] [Verified]

Quick Navigation:

1. 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 • 🤝 Contributing • ⚖️ Third-Party Licenses • 📄 Plain Text SBOM • 🤖 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

ASCII Four-View Architectural Topology

+--------------------------------------------------------------------------------------------------+|                            ELLMOS FILECOMMANDER MCP ARCHITECTURAL TOPOLOGY                       |+--------------------------------------------------------------------------------------------------+| [VIEW 1: CALLER RUNTIMES & AGENT CLIENTS]                                                        ||   * Autonomous Agents   : Claude Code, OpenAI Codex, Antigravity / Gemini, Kimi, Cursor          ||   * Agent Frameworks    : AutoGen, CrewAI, LangChain, LlamaIndex, Custom Python / TS Clients    ||   * Transport Protocols : Model Context Protocol (MCP stdio), JSON-RPC 2.0 Framing               ||   * Tool Surface        : 50 Unified Specialized Tools (fc_* namespace collision isolation)       ||   * Schema Contract     : Stdio transport, dynamic runtime i18n parameter parsing (Zod validated)|+--------------------------------------------------------------------------------------------------+|                                                |                                                 ||                                                v                                                 |+--------------------------------------------------------------------------------------------------+| [VIEW 2: FILECOMMANDER MCP CORE ENGINE & DISPATCH ORCHESTRATOR]                                  ||   * Protocol Dispatch   : ESM stdio router with Zod schema validation & parameter checking      ||   * Multilingual Core   : 11-language dynamic runtime i18n engine       ||   * Safety Interceptor  : Global Safety Mode (fc_set_safe_mode) routing deletes to Recycle Bin   ||   * Sync Diagnostics    : Reparse point detection & cloud filter diagnostics (fc_check_cloud_lock)||   * Process Supervisor  : Bounded child process lifecycle management & interactive REPL session  ||                           state registry with circular ring buffers                              |+--------------------------------------------------------------------------------------------------+|                                                |                                                 ||                                                v                                                 |+--------------------------------------------------------------------------------------------------+| [VIEW 3: FILESYSTEM RUNTIME, FORMAT REPAIR & PROCESS ISOLATION]                                  ||   * Atomic File Ops     : Read, write, line edit, exact literal string replacement (fc_str_replace)||   * Cloud-Lock Fallback : Automatic copyFileSync + SHA-256 verify + unlinkSync on EPERM / EBUSY   ||   * Bounded Inspection  : Metadata-first preview (fc_preview_file, 1 MiB inline content ceiling)  ||   * Bounded Content Srch: max 50 explicit files, 10 MB ceiling, token redaction (INV-MASK-06)   ||   * Self-Healing Repair : Mojibake repair (27+ UTF-8 patterns), JSON syntax fix, file cleanup    ||   * Lossless Converter  : Declarative transformation across 7 formats (JSON, YAML, TOML, XML...) ||   * Media & Documents   : Headless Markdown to PDF/HTML, ZIP archive engine, optional OCR (Tess)  |+--------------------------------------------------------------------------------------------------+|                                                |                                                 ||                                                v                                                 |+--------------------------------------------------------------------------------------------------+| [VIEW 4: AIR-GAP DEFENSE PERIMETER, RUNASINVOKER & CONTROLLED EGRESS]                            ||   * Execution Privilege : RunAsInvoker unprivileged user-mode (Zero administrative elevation)    ||   * Transport Boundary  : 100% Local stdio transport, zero telemetry, zero open listening ports  ||   * Controlled Egress   : Outbound HTTP(S) strictly gated through caller-invoked fc_web_fetch     ||   * Network Safety      : SSRF guard blocking private/internal IP ranges (allow_private override) ||   * Governance & Supply : Level 1 SBOM, 100% permissive runtime (MIT/BSD), 48h Security SLA      |+--------------------------------------------------------------------------------------------------+

Component Flow Diagram

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
    Note over AI,FC: 3. Bounded Preview & Remote Safety (fc_preview_file)    AI->>FC: fc_preview_file(path, include_content=false)    FC->>FS: Metadata-only inspection (size, MIME type, preview kind)    FS-->>FC: File stat (e.g. 500 KB, text/plain)    FC-->>AI: Structured preview descriptor (1 MiB ceiling enforced)    opt Explicit Content Retrieval        AI->>FC: fc_preview_file(path, include_content=true)        FC->>FS: Read bounded content block        FS-->>FC: Raw content bytes        FC-->>AI: Standard MCP text/image content block    end

Core Capabilities & Safety Invariants

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 ([email protected], [email protected]).

[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

npm install -g ellmos-filecommander-mcp

Option 2: Install from Source

git clone https://github.com/ellmos-ai/ellmos-filecommander-mcp.gitcd ellmos-filecommander-mcpnpm cinpm 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:

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

If installed from source:

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

Restart Claude Desktop after saving.

Claude Code CLI

Add FileCommander to Claude Code via CLI:

claude mcp add filecommander -- ellmos-filecommander

Or configure directly in ~/.claude.json under mcpServers.

Gemini CLI

Merge the following mcpServers entry into ~/.gemini/settings.json for the current user, or .gemini/settings.json in your project. On Windows, ~ is %USERPROFILE%. Preserve other settings and existing servers. See the official Gemini CLI configuration reference.

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

Antigravity

Merge the same server entry into ~/.gemini/config/mcp_config.json globally, or .agents/mcp_config.json in your workspace. These paths differ from Gemini CLI settings. Preserve existing entries; for the IDE you can also open MCP Servers → Manage MCP Servers → View raw config. See the official Antigravity MCP reference.

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

Cursor IDE

Add to .cursor/mcp.json:

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

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)

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)

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)

Process Management (5 tools)

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)

File Maintenance & Repair (9 tools)

Archive (1 tool)

OCR (1 tool)

Cloud Sync (1 tool)

System (4 tools)

Export (2 tools)

Web (1 tool)

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:

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:

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

# Install dependenciesnpm ci
# Watch mode (auto-rebuild on changes)npm run dev
# One-time buildnpm run build
# Start the servernpm start
# Run test suitenpm test

Testing

The project includes 250 Vitest tests plus 71 standalone i18n checks (321 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.

npm test              # Run all testsnode test-i18n.mjs    # Run standalone i18n checksnpx vitest run        # Same as abovenpx 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:

npm uninstall -g bach-filecommander-mcpnpm 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

AI Infrastructure

Desktop Software & Sibling Applications

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

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 [email protected] und [email protected] 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 [email protected] and [email protected] with formal triage within 5 business days.