fs-mcp-rs

A fast, configurable filesystem server for the Model Context Protocol (MCP), written in Rust.

fs-mcp-rs gives an MCP client a small set of filesystem tools while keeping access inside directories selected by the operator. It has no implicit filesystem root, no built-in personal path, and no writable default. The server starts only when you provide a configuration file.

Why one crate?

The public distribution is one crate and one executable, both named fs-mcp-rs. The protocol, policy, filesystem, search, and settings components remain separate Rust modules inside that crate. This keeps installation simple:

cargo install fs-mcp-rs

Users do not need to install or understand a graph of internal crates. The benchmark runner remains a development-only workspace member and is not included in the crates.io package.

Features

• MCP over JSON-RPC HTTP POST and line-delimited STDIO (stdin/stdout).
• Zero-install execution via npx fs-mcp-rs.
• Explicit allow-list of one or more filesystem roots (via CLI positional arguments or TOML config).
• Read-only mode for safe deployments.
• Optional write, move, edit, directory creation, and removal operations.
• Bounded reads, writes, search results, and concurrency.
• Literal and regular-expression content search.
• .gitignore support and configurable hidden-file handling.
• Symlink traversal disabled by default.
• Atomic file replacement and BLAKE3 hashes.
• Optional arbitrary terminal command execution with time and output limits.
• Persistent terminal sessions with incremental output cursors, long polling, stdin, process-tree termination, retention, and bounded buffers.
• Concise tool execution logging ([OK] / [WARN]).
• No telemetry and no automatic network discovery.

Requirements

• Node.js (v18+) for npx execution, or Rust 1.85+ when building from source.
• An MCP client that can connect via STDIO JSON-RPC or Streamable HTTP/JSON-RPC endpoint.
• A configuration file or explicit root paths passed to the server.

Installation

Via npx (Zero Installation)

The easiest way to run fs-mcp-rs with any MCP client (such as Claude Desktop or Cursor) is using npx:

npx fs-mcp-rs /path/to/project

The npm package automatically downloads the appropriate precompiled binary for your operating system and architecture (Windows x64, Linux x64, macOS x64/arm64).

From crates.io

cargo install fs-mcp-rs
fs-mcp-rs --version

From source

git clone https://github.com/nihmadev/fs-mcp-rs.git
cd fs-mcp-rs
cargo build --release

The executable will be at target/release/fs-mcp-rs on Unix-like systems or target\release\fs-mcp-rs.exe on Windows.

Create a configuration

Copy configs/example.toml somewhere appropriate and edit it. The server intentionally has no default config path:

cp configs/example.toml fs-mcp-rs.toml

Windows PowerShell:

Copy-Item configs\example.toml fs-mcp-rs.toml

Minimal read-only configuration:

[server]
host = "127.0.0.1"
port = 8000
max_concurrency = 32
max_io_concurrency = 16

[filesystem]
roots = ["/home/alice/projects"]
read_only = true
max_read_bytes = 8388608
max_write_bytes = 8388608
follow_links = false

[search]
max

... [View full README on GitHub](https://github.com/nihmadev/fs-mcp-rs#readme)