BACH FileCommander MCP Server

Part of the ellmos-ai family.

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

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

Why FileCommander?

Most filesystem MCP servers only cover basic read/write operations. FileCommander goes further:

• Safe Delete - Moves files to Recycle Bin (Windows) or Trash (macOS/Linux) instead of permanent deletion
• Interactive Sessions - Start and interact with REPLs (Python, Node.js, shells) through the MCP protocol
• Async Search - Search large directory trees in the background while the AI continues working
• Process Management - List, start, and terminate system processes
• String Replace - Edit files by matching unique strings with context validation
• Format Conversion - Convert between JSON, CSV, INI, YAML, TOML, XML, and TOON
• ZIP Archives - Create, extract, and list ZIP archives
• File Checksums - SHA-256, MD5, SHA-1, SHA-512 hashing with compare
• OCR - Extract text from images (optional tesseract.js dependency)
• Safety Mode - Toggle to route all deletes through Recycle Bin / Trash
• Markdown Export - Convert Markdown to professional HTML/PDF with code blocks, tables, nested lists, blockquotes
• Cross-platform - Works on Windows, macOS, and Linux with platform-specific optimizations

Installation

Prerequisites

• Node.js 18 or higher
• npm

Option 1: Install from NPM

npm install -g bach-filecommander-mcp

Option 2: Install from Source

git clone https://github.com/lukisch/bach-filecommander-mcp.git
cd bach-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": "bach-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 bach-filecommander binary.

Tools Overview

Filesystem Operations (14 tools)

Async Search (5 tools)

Process Management (4 tools)

Interactive Sessions (5 tools)

File Maintenance & Repair (8 tools)

Archive (1 tool)

OCR (1 tool)

System (2 tools)

Export (2 tools)

Total: 43 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
• Most comprehensive single-server solution (43 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.

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

See CONTRIBUTING.md for contribution guidelines.

Changelog

See CHANGELOG.md for the full version history.

License

MIT - Lukas (BACH)