ellmos FileCommander MCP Server

🇩🇪 Deutsche Version

Part of the ellmos-ai family.

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

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

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 Toolkit

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 (47 Tools)"]
        FS["Filesystem & Cloud-Lock Guard\n(14 tools: read, 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(9 tools: exec, background proc, interactive REPLs)"]
        Repair["Repair & Format Converter\n(9 tools: JSON fix, Mojibake fix, duplicates, format convert)"]
        Export["Export & Web Scraper\n(3 tools: Markdown->HTML/PDF, web_fetch)"]
        Sys["System & Utilities\n(6 tools: OCR, ZIP, checksums, safe-mode, time)"]
    end

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

Installation

Prerequisites

• Node.js 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.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:

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

Other MCP Clients

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

Tools Overview

Filesystem Operations (14 tools)

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

Interactive Sessions (5 tools)

File Maintenance & Repair (9 tools)

Archive (1 tool)

OCR (1 tool)

Cloud Sync (1 tool)

System (2 tools)

Export (2 tools)

Web (1 tool)

Total: 47 tools

Comparison with Alternatives

Key differentiators:

• Only MCP server with recoverable delete (Recycle Bin / Trash)

• Only MCP server with async background search with pagination

• Built-in JSON repair, encoding fix, and duplicate detection

• Only MCP server with cloud-lock-safe file operations (automatic copy+delete fallback)

• Most comprehensive single-server solution (47 tools)

• Built-in safety mode to prevent accidental permanent deletion

Tool Prefix

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

Discoverability

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

• package.json exposes the official mcpName (io.github.ellmos-ai/ellmos-filecommander-mcp) and MCP-specific npm keywords.

• server.json follows the official MCP Registry schema and points to the npm package.

• glama.json provides MCP-directory metadata for Glama-compatible indexes.

• llms.txt gives compact context for LLMs, agent catalogs, and documentation crawlers.

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

External discovery notes: npm and jsDelivr may show the previously published metadata until version 1.10.0 is released. LobeHub indexes the GitHub repo as an MCP server. Use the package description and this README as the canonical 47-tool source for the current repository.

Security

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

See SECURITY.md for detailed security information and recommendations.

Key points:

• fc_execute_command runs arbitrary shell commands

• fc_delete_* tools perform permanent deletion by default (use fc_safe_delete or enable safe mode via fc_set_safe_mode to route all deletes through Recycle Bin / Trash)

• No built-in sandboxing - security is delegated to the MCP client layer

• Designed for local use via stdio transport only

Development

# 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 175 Vitest tests plus 69 standalone i18n checks (244 total) covering filesystem operations, bounded content search, format conversion, encoding repair, archive handling, duplicate detection, language packs, and more.

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

MIT - Lukas Geiger (ellmos-ai)

History

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

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

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

AI Infrastructure

Desktop Software

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

Haftung / Liability

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

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

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