Skip to main content
Glama
ellmos-filecommander-mcp

ellmos-filecommander-mcp

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


Related MCP server: MCP TS Toolkit

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

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.

Eleven-language Runtime i18n Engine

Dynamic language switching and reporting (fc_set_language, fc_get_language) for all 11 supported codes: de, en, es, zh, ja, ru, fr, hi, ar, bn, and pt.

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

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.git
cd ellmos-filecommander-mcp
npm ci
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:

{
  "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)

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, ru, fr, hi, ar, bn, or pt)

fc_get_language

Read the active runtime language and all 11 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

# Install dependencies
npm ci

# 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 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 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.


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-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

Zombie Killer Tray

Process Management

dev-bricks

Optional Windows tool for checking orphaned MCP processes. FileCommander is a configured candidate when launched through the supported node_modules/ellmos-filecommander-mcp/dist/index.js entrypoint; all additional process and apply checks still apply.


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.

Available Tools

50 tools
fc_archiveArchive (ZIP)C
Destructive

Erstellt, entpackt und listet ZIP-Archive.

Inputs: action (required), archive_path (required), extract_to, source_paths.

fc_batch_renameBatch RenameB
Destructive

Renames files by pattern: remove prefix/suffix, replace, or auto-detect.

Args:

  • directory (string): Directory with the files

  • mode (string): "remove_prefix" | "remove_suffix" | "replace" | "auto_detect"

  • pattern (string, optional): Text to remove/replace

  • replacement (string, optional): Replacement text (for replace mode)

  • extensions (string, optional): Filter by extensions

  • dry_run (boolean): Preview only

Examples:

  • Remove prefix: mode="remove_prefix", pattern="backup_"

  • Auto-detect: mode="auto_detect" detects common prefixes

Inputs: mode (required), directory (required), dry_run, pattern, +2 more.

fc_check_cloud_lockCheck Cloud LockC
Read-onlyIdempotent

Meldet statischen Cloud-Sync-Kontext und verfügbaren Zielzustand. Sie behauptet keine aktive Sperre. Nur auf Windows relevant.

Inputs: path (required).

fc_checksumFile ChecksumC
Read-onlyIdempotent

Berechnet Prüfsummen (MD5/SHA1/SHA256/SHA512) für Dateien.

Inputs: file_path (required), compare, algorithm.

fc_cleanup_fileCleanup FileC
Idempotent

Cleans up one or more files from common problems.

Args:

  • path (string): Path to file or directory

  • recursive (boolean, optional): Recursive for directories

  • extensions (string, optional): Filter file extensions (e.g. ".txt,.json,.py")

  • remove_bom (boolean): Remove UTF-8 BOM

  • remove_trailing_whitespace (boolean): Remove trailing whitespace

  • normalize_line_endings (string, optional): "lf" | "crlf" | null

  • remove_nul_bytes (boolean): Remove NUL bytes

  • dry_run (boolean): Preview only

Cleans: BOM, NUL bytes, trailing whitespace, line endings

Inputs: path (required), dry_run, recursive, extensions, +4 more.

fc_close_sessionClose SessionA
DestructiveIdempotent

Terminates a running session and removes it from the list.

Args:

  • session_id (string): Session ID

  • force (boolean, optional): Force termination

Inputs: session_id (required), force.

fc_convert_formatConvert FormatB
Idempotent

Converts files between different formats.

Args:

  • input_path (string): Path to source file

  • output_path (string): Path to target file

  • input_format (string): "json" | "csv" | "ini" | "yaml" | "toml" | "xml" | "toon"

  • output_format (string): "json" | "csv" | "ini" | "yaml" | "toml" | "xml" | "toon"

  • json_indent (number, optional): JSON indentation (default: 2)

Supported conversions:

  • JSON <-> CSV (for arrays of objects)

  • JSON <-> INI (for flat objects/sections)

  • JSON <-> YAML

  • JSON <-> TOML

  • JSON <-> XML

  • JSON <-> TOON (hierarchical key-value format)

  • JSON pretty-print / minify

Inputs: input_path (required), output_path (required), input_format (required), output_format (required), +1 more.

fc_copyCopyC

Copies a file or directory.

Args:

  • source (string): Source path

  • destination (string): Destination path

  • recursive (boolean): Copy directories recursively

Inputs: source (required), destination (required), recursive.

fc_create_directoryCreate DirectoryB
Idempotent

Creates a new directory (including parent directories).

Args:

  • path (string): Path to the new directory

Returns:

  • Confirmation of creation

Inputs: path (required).

fc_delete_directoryDelete DirectoryB
DestructiveIdempotent

Deletes a directory.

Args:

  • path (string): Path to the directory

  • recursive (boolean): Delete non-empty directories too

Warning: With recursive=true ALL contents are irreversibly deleted!

Inputs: path (required), recursive.

fc_delete_fileDelete FileA
DestructiveIdempotent

Deletes a file.

Args:

  • path (string): Path to the file

Warning: Irreversible! No recycle bin.

Inputs: path (required).

fc_detect_duplicatesDetect DuplicatesA
Read-onlyIdempotent

Finds file duplicates in a directory using SHA-256 hashes.

Args:

  • directory (string): Directory to scan

  • recursive (boolean): Search recursively

  • extensions (string, optional): Filter by extensions

  • min_size (number, optional): Minimum size in bytes (default: 1)

  • max_size (number, optional): Maximum size in bytes

Returns:

  • Groups of duplicates with paths and sizes

Inputs: directory (required), max_size, min_size, recursive, +1 more.

fc_edit_fileEdit File (Lines)A
Destructive

Edits a file line-based: replace, insert, or delete.

Args:

  • path (string): Path to the file

  • operation (string): "replace" | "insert" | "delete"

  • start_line (number): Start line (1-based)

  • end_line (number, optional): End line for replace/delete

  • content (string, optional): New content for replace/insert

Examples:

  • Replace lines 5-10: operation="replace", start_line=5, end_line=10, content="new text"

  • Insert after line 3: operation="insert", start_line=3, content="new line"

  • Delete lines 7-9: operation="delete", start_line=7, end_line=9

Inputs: path (required), operation (required), start_line (required), content, +1 more.

fc_execute_commandExecute CommandB
Destructive

Executes a shell command and returns the output.

Args:

  • command (string): Command to execute

  • cwd (string, optional): Working directory

  • timeout (number, optional): Timeout in milliseconds (default: 30000)

Warning: Commands are executed with user privileges!

Examples:

  • command: "dir" (Windows)

  • command: "ls -la" (Unix)

  • command: "python --version"

Inputs: command (required), cwd, timeout.

fc_file_infoFile InformationB
Read-onlyIdempotent

Shows detailed information about a file/directory.

Args:

  • path (string): Path to the file/directory

Returns:

  • Size, type, creation/modification date, permissions

Inputs: path (required).

fc_fix_encodingFix EncodingB
Idempotent

Detects and repairs encoding errors (mojibake, double UTF-8).

Args:

  • path (string): Path to the file

  • dry_run (boolean): Only show problems

  • create_backup (boolean): Create backup

Repairs common mojibake patterns like:

  • ä -> ae, ö -> oe, ü -> ue (German umlauts)

  • ß -> ss, € -> EUR

Inputs: path (required), dry_run, create_backup.

fc_fix_jsonFix JSONB
Idempotent

Automatically repairs common JSON errors.

Args:

  • path (string): Path to the JSON file

  • dry_run (boolean, optional): Only show problems, do not repair

  • create_backup (boolean, optional): Create backup before repair

Repairs: BOM, trailing commas, single quotes, comments, NUL bytes

Inputs: path (required), dry_run, create_backup.

fc_folder_diffFolder DiffA
Read-onlyIdempotent

Compares the current state of a directory with a saved snapshot.

Args:

  • path (string): Path to the directory

  • save_snapshot (boolean): Save current state as new snapshot

  • extensions (string, optional): Filter file extensions

Detects: New files, modified files, deleted files Snapshots are saved in %TEMP%/.fc_snapshots/

Inputs: path (required), extensions, save_snapshot.

fc_get_languageGet LanguageA
Read-onlyIdempotent

Get the active output language and all supported language codes

Inputs: no named parameters.

fc_get_search_resultsGet Search ResultsA
Read-onlyIdempotent

Retrieves results of a running or completed search.

Args:

  • search_id (string): Search ID from fc_start_search

  • offset (number, optional): Start offset for pagination

  • limit (number, optional): Maximum number of results (default: 50)

Returns:

  • Search status and found files

Inputs: search_id (required), limit, offset.

fc_get_timeCurrent TimeA
Read-only

Returns the current system time.

Returns:

  • Date, time, weekday, timezone

Inputs: no named parameters.

fc_kill_processKill ProcessB
DestructiveIdempotent

Terminates a process by PID or name.

Args:

  • pid (number, optional): Process ID

  • name (string, optional): Process name

  • force (boolean): Force termination

Warning: May cause data loss!

Inputs: pid, name, force.

fc_list_directoryList DirectoryB
Read-onlyIdempotent

Lists files and subdirectories.

Args:

  • path (string): Path to the directory

  • depth (number, optional): Maximum depth for recursive listing (default: 1)

  • show_hidden (boolean, optional): Show hidden files

Returns:

  • Formatted list of all entries with icons

Inputs: path (required), depth, show_hidden.

fc_list_processesList ProcessesA
Read-onlyIdempotent

Lists running system processes.

Args:

  • filter (string, optional): Filter by process name

Returns:

  • List of processes with PID, name, memory

Note: Uses 'tasklist' (Windows) or 'ps' (Unix)

Inputs: filter.

fc_list_searchesList SearchesA
Read-onlyIdempotent

Lists all active and completed background searches.

Inputs: no named parameters.

fc_list_sessionsList SessionsB
Read-onlyIdempotent

Lists all active and ended sessions.

Returns:

  • Table of all sessions with status

Inputs: no named parameters.

fc_md_to_htmlMarkdown to HTMLB
Idempotent

Converts Markdown to formatted HTML (printable as PDF).

Args:

  • input_path (string): Path to Markdown file

  • output_path (string): Path to HTML output

  • title (string, optional): Document title

Generates standalone HTML with CSS styling, printable as PDF via browser.

Inputs: input_path (required), output_path (required), title.

fc_md_to_pdfMarkdown to PDFA
Idempotent

Converts Markdown to PDF using a headless browser (Edge/Chrome).

Args:

  • input_path (string): Path to the Markdown file

  • output_path (string): Path to the PDF output

  • title (string, optional): Document title

Uses the same Markdown parser as fc_md_to_html. Requires Edge or Chrome. Falls back to HTML if no browser is found.

Inputs: input_path (required), output_path (required), title.

fc_moveMove/RenameB
Destructive

Moves or renames a file/directory.

Args:

  • source (string): Source path

  • destination (string): Destination path

Examples:

  • Rename: source="test.txt", destination="test_new.txt"

  • Move: source="C:\a\test.txt", destination="C:\b\test.txt"

Inputs: source (required), destination (required).

fc_ocrOCR - Text from Image/PDFC
DestructiveIdempotent

Extrahiert Text aus Bildern (JPG/PNG/BMP/TIFF) mittels OCR (Tesseract).

Inputs: file_path (required), language, output_path.

fc_open_pathOpen PathA

Startet für eine vorhandene lokale Datei oder einen Ordner die Standardanwendung. Die strukturierte Rückgabe trennt launcher_accepted von user_visible=unknown und nennt einen Remote-Fallback.

Inputs: path (required). Returns: path, fallback, launcher, platform, +4 more

fc_preview_filePreview FileA
Read-onlyIdempotent

Liefert zuerst MIME-Typ, Größe und Vorschaufähigkeit einer lokalen Datei. Inhalt wird nur nach include_content=true und nur bis zum festen Inline-Limit als MCP-Text-, Bild- oder Resource-Content zurückgegeben.

Inputs: path (required), include_content. Returns: uri, path, reason, mime_type, +6 more

fc_read_fileRead FileB
Read-onlyIdempotent

Reads the content of a file.

Args:

  • path (string): Full path to the file

  • encoding (string, optional): Character encoding (default: utf-8)

  • max_lines (number, optional): Maximum number of lines (0 = all)

Returns:

  • File content as text

  • For binary files: Base64-encoded content

Examples:

  • path: "C:\Users\User\test.txt"

  • path: "/home/user/config.json"

Inputs: path (required), encoding, max_lines.

fc_read_multiple_filesRead Multiple FilesA
Read-onlyIdempotent

Reads multiple files at once and returns their contents.

Args:

  • paths (array): Array of file paths

  • max_lines_per_file (number, optional): Max lines per file (0 = all)

Returns:

  • Contents of all files with separators

Example: paths: ["C:\config.json", "C:\readme.md"]

Inputs: paths (required), max_lines_per_file.

fc_read_outputRead Session OutputA
Read-onlyIdempotent

Reads the output of a running session.

Args:

  • session_id (string): Session ID from fc_start_session

  • clear (boolean, optional): Clear output after reading

Returns:

  • Collected output since start/last clear

Inputs: session_id (required), clear.

fc_safe_deleteSafe Delete (Recycle Bin)A
Idempotent

Moves files/directories to recycle bin instead of deleting them.

Args:

  • path (string): Path to the file/directory

SAFE: Can be restored from the recycle bin!

Note: Uses Windows recycle bin or creates backup on other systems.

Inputs: path (required).

fc_search_contentSearch File ContentA
Read-onlyIdempotent

Durchsucht ausschließlich explizit übergebene Dateien nach Text. Standardmäßig literal, optional mit regulärem Ausdruck; deterministische begrenzte JSON-Ausgabe, dateibezogene Teilfehler, Binärdatei-Skip, Kontextzeilen und Geheimnis-Redaktion. Keine Glob-Auflösung und keine Verzeichnisrekursion.

Inputs: paths (required), query (required), regex, max_results, +3 more.

fc_search_filesSearch FilesB
Read-onlyIdempotent

Searches files by name/pattern in a directory.

Args:

  • directory (string): Start directory for the search

  • pattern (string): Search pattern (supports * and ? wildcards)

  • max_results (number, optional): Maximum results (default: 50)

Examples:

  • pattern: "*.txt" - All text files

  • pattern: "test*" - Files starting with "test"

  • pattern: "*.py" - All Python files

Inputs: pattern (required), directory (required), max_results.

fc_send_inputSend Input to SessionB
Destructive

Sends input to a running session.

Args:

  • session_id (string): Session ID

  • input (string): Input to send

  • newline (boolean, optional): Append newline (default: true)

Examples:

  • Python: input="print('Hello')"

  • Shell: input="ls -la"

Inputs: input (required), session_id (required), newline.

fc_set_languageSet LanguageA
Idempotent

Set the output language for FileCommander tools

Inputs: language (required).

fc_set_safe_modeSet Safe ModeA
Idempotent

Aktiviert/deaktiviert den Safe Mode. Wenn aktiv, werden alle Löschoperationen (fc_delete_file, fc_delete_directory) über den Papierkorb umgeleitet.

Inputs: enabled (required).

fc_start_processStart ProcessA
Destructive

Starts a process in the background (non-blocking).

Args:

  • program (string): Program/Executable

  • args (array, optional): Arguments as array

  • cwd (string, optional): Working directory

Examples:

  • program: "notepad.exe", args: ["test.txt"]

  • program: "python", args: ["script.py"]

  • program: "code", args: ["."] (open VS Code)

Inputs: program (required), cwd, args.

fc_start_sessionStart Interactive SessionA
Destructive

Starts an interactive process as a session (for fc_read_output and fc_send_input).

Args:

  • command (string): Command/Program

  • args (array, optional): Arguments

  • cwd (string, optional): Working directory

Returns:

  • Session ID for further interaction

Examples:

  • Python REPL: command="python"

  • Node REPL: command="node"

  • PowerShell: command="powershell"

Inputs: command (required), cwd, args.

fc_str_replaceString Replace in FileA
Destructive

Replaces a unique string in a file with another.

Args:

  • path (string): Path to the file

  • old_str (string): String to replace (must occur exactly once)

  • new_str (string): New string (empty = delete)

Returns:

  • Confirmation with context

IMPORTANT: old_str must occur EXACTLY once in the file! An error is returned for 0 or >1 occurrences.

Examples:

  • Rename function: old_str="def old_name", new_str="def new_name"

  • Add import: old_str="import os", new_str="import os\nimport sys"

  • Delete line: old_str="# TODO: remove this\n", new_str=""

Inputs: path (required), old_str (required), new_str.

fc_validate_jsonValidate JSONB
Read-onlyIdempotent

Validates a JSON file and shows detailed error information.

Args:

  • path (string): Path to the JSON file

Returns:

  • Validation status with line/column on errors

Inputs: path (required).

fc_web_fetchWeb FetchA
Read-onlyIdempotent

Ruft eine Webseite ab und gibt je nach Modus Inhalt zurück: extract (sauberer Haupttext), raw (HTTP-Body, gekürzt), links, forms oder headers. Nur lesendes Netzwerk-Tool; interne/private Ziele sind standardmäßig blockiert (allow_private zum Überschreiben).

Inputs: url (required), mode, allow_private, timeout_seconds.

fc_write_fileWrite FileA
Destructive

Writes content to a file. Creates the file if it does not exist.

Args:

  • path (string): Full path to the file

  • content (string): Content to write

  • append (boolean, optional): Append to file instead of overwriting

  • create_dirs (boolean, optional): Create missing directories

Returns:

  • Confirmation with file size

Warning: Overwrites existing files without warning when append=false!

Inputs: path (required), content (required), append, create_dirs.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 50 tools

    Disambiguation3/5

    Most tools target distinct operations, but several clusters overlap: fc_search_files vs fc_start_search/fc_get_search_results (synchronous vs background search of the same pattern), fc_write_file vs fc_edit_file vs fc_str_replace (all mutate file content), and fc_cleanup_file vs fc_fix_json/fc_fix_encoding (all strip BOM/NUL bytes). The execute/process/session trio (fc_execute_command, fc_start_process, fc_start_session) is also boundary-blurry, though descriptions do help differentiate them.

    Naming Consistency4/5

    All names use a consistent fc_ prefix with snake_case, which is predictable. A few names omit the verb (fc_copy, fc_move, fc_file_info, fc_checksum, fc_archive, fc_ocr, fc_folder_diff), a minor deviation from the dominant verb_noun pattern but still readable and unambiguous.

    Tool Count2/5

    50 tools is far too many for a file-commander surface and sprawls well beyond file operations into OCR, PDF generation, format conversion, archive handling, process management, sessions, and web fetching. Many capabilities are niche and could be consolidated, making the set hard to scan before selection.

    Completeness4/5

    Core file lifecycle is thoroughly covered (create, read, write, edit, move, copy, delete, info, safe delete, search, bulk operations), plus extras like hashing, archives, OCR, and conversions. Minor gaps remain around permissions/attributes and symlink handling, but no significant dead ends for typical workflows.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A comprehensive MCP server providing secure tools for filesystem operations, Git management, web search, document conversion, npm/.NET project management, and AI generative capabilities (image/video/audio generation and processing) via PiAPI.ai integration.
      Apache 2.0
    • A
      license
      B
      quality
      D
      maintenance
      A comprehensive MCP server with 30+ custom tools organized into categories: date/time operations, file management, system information, text processing, and web operations. Enables async communication with robust error handling and flexible CLI integration.
      31
      1
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Utility-first MCP server that extends Claude Code with file-maintenance capabilities beyond built-in tools. Supports encoding repair, format conversion, duplicate detection, batch renaming, and archive utilities.
      12
      83 npm
      1
      MIT