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_results = 1000 max_concurrency = 4 worker_threads = 4 regex_cache_capacity = 64 include_hidden = false respect_gitignore = true

WARNING: enables arbitrary commands with the server process permissions.

[terminal] enabled = true max_concurrency = 2 default_timeout_ms = 30000 max_timeout_ms = 300000 max_output_bytes = 4194304

Windows roots use escaped backslashes or forward slashes:

roots = ["C:\\Users\\Alice\\Projects", "D:/Shared/Documentation"]

Relative roots are resolved relative to the directory containing the configuration file, not relative to an arbitrary process working directory.

Configuration reference

[server]

• host: IP address to bind. Keep 127.0.0.1 unless remote clients genuinely need access.
• port: TCP port for /health and /mcp.
• max_concurrency: maximum number of MCP requests processed at once.
• max_io_concurrency: maximum number of simultaneous non-search filesystem jobs.
• log_tools: whether concise tool execution logging ([OK] / [WARN]) is printed (default: true).

[filesystem]

• roots: non-empty list of allowed directories. Every requested path must resolve inside one of them.
• read_only: when true, all mutating tools are rejected.
• max_write_bytes: largest permitted write_file or resulting edit_text content.
• follow_links: whether paths containing symbolic links may be followed. Leave this false unless you have reviewed the consequences.

[search]

• max_results: maximum matches returned by one search.
• max_concurrency: maximum simultaneous search jobs.
• worker_threads: filesystem traversal threads used by each search.
• regex_cache_capacity: number of compiled search patterns cached in memory; 0 disables the cache.
• include_hidden: include hidden files and directories.
• respect_gitignore: apply Git ignore files while walking directories.

[terminal]

• enabled: expose command execution. When disabled, run_command returns a tool error.
• max_concurrency: maximum terminal commands running simultaneously.
• default_timeout_ms: timeout used when a call does not provide one.
• max_timeout_ms: largest timeout a call may request.
• max_output_bytes: maximum combined stdout/stderr bytes retained per terminal session. Old output is evicted and reported as dropped/truncated.
• max_read_bytes: maximum output bytes returned by one terminal_read call.
• max_wait_ms: maximum long-poll duration for one terminal_read call.
• session_retention_ms: how long completed sessions and their output remain readable before automatic cleanup.

run_command executes arbitrary commands through cmd.exe on Windows and /bin/sh on GNU/Linux and macOS. It is advertised with destructive and open-world MCP annotations so compatible providers can show a warning. Enabling it gives commands all permissions of the operating-system account running the server; filesystem roots and read-only mode do not sandbox terminal commands.

Unknown fields and zero-valued safety limits are rejected. This catches misspelled settings instead of silently ignoring them.

Start the server

Positional root paths (Quickstart)

Start directly by specifying allowed filesystem directories on the command line:

fs-mcp-rs /home/alice/project1 /home/alice/project2

If no configuration file or positional roots are passed, fs-mcp-rs uses default settings scoped to the current working directory.

With a configuration file

Pass the configuration explicitly:

fs-mcp-rs --config /absolute/path/to/fs-mcp-rs.toml

Or use the environment variable:

FS_MCP_CONFIG=/absolute/path/to/fs-mcp-rs.toml fs-mcp-rs

PowerShell:

$env:FS_MCP_CONFIG = "C:\config\fs-mcp-rs.toml"

fs-mcp-rs

Transport Modes (STDIO vs HTTP)

• STDIO Mode: Activated automatically when stdout/stdin are non-interactive pipes (e.g. when spawned as an MCP subprocess) or when passing --stdio. Structured logs are written to stderr to keep stdout clean for line-delimited JSON-RPC messages.
• HTTP Mode: Activated by default during interactive execution. Listens on the configured host/port for /health and /mcp endpoints.

Check HTTP health:

curl http://127.0.0.1:8000/health

Expected response:

ok

The MCP endpoint is:

http://127.0.0.1:8000/mcp

Start the server and a tunnel together

The run subcommand always starts the MCP server in HTTP mode and can manage an ngrok, Cloudflare Quick Tunnel, or zrok public share in the same process lifecycle:

fs-mcp-rs run --ngrok /path/to/allowed/directory

fs-mcp-rs run --ngrok --config ./fs-mcp-rs.toml fs-mcp-rs run --cloudflared /path/to/allowed/directory fs-mcp-rs run --zrok /path/to/allowed/directory

The providers are mutually exclusive. On Windows, the tunnel opens in a new console by default. Use --tunnel-window hidden to avoid a separate visible console while keeping the generated URL in the current terminal, or --tunnel-window inherit to attach normally. On Linux and macOS, new inherits the current terminal because creating a terminal window is desktop-specific. Each provider accepts repeatable extra arguments and an explicit executable path:

fs-mcp-rs run --ngrok --tunnel-window hidden --ngrok-arg=--region=eu

fs-mcp-rs run --ngrok --ngrok-bin /opt/ngrok/ngrok fs-mcp-rs run --cloudflared --cloudflared-arg=--no-autoupdate fs-mcp-rs run --zrok --zrok-bin /opt/zrok/zrok

Stopping the MCP server also stops the tunnel process. Existing invocations such as fs-mcp-rs [PATHS], fs-mcp-rs --config FILE, and fs-mcp-rs serve are unchanged. The earlier --ngrok-window spelling remains an alias for --tunnel-window.

Expose the server through a secure tunnel

For testing with a remote MCP client, keep fs-mcp-rs bound to loopback and expose it through a tunnel. Start the server first:

fs-mcp-rs --config ./fs-mcp-rs.toml

Verify the local endpoint before creating a tunnel:

curl http://127.0.0.1:8000/health

[!CAUTION]

A public tunnel URL gives remote clients a path to the tools and filesystem roots allowed by your configuration. Start with read_only = true, grant only narrowly scoped roots, never expose secrets, and stop the tunnel when it is no longer needed. Quick tunnels are intended for development—not permanent production hosting.

Cloudflare Tunnel

Install cloudflared, then create a temporary Quick Tunnel:

cloudflared tunnel --url http://127.0.0.1:8000

cloudflared prints a temporary URL similar to https://random-name.trycloudflare.com. Use the MCP endpoint with /mcp appended:

https://random-name.trycloudflare.com/mcp

For a stable hostname, create a named Cloudflare Tunnel, map a DNS hostname to it, and route that hostname to http://127.0.0.1:8000. Protect long-lived deployments with Cloudflare Access or another authentication layer.

ngrok

Install ngrok, authenticate its CLI if required by your account, and start an HTTP tunnel:

ngrok http 8000

Use the HTTPS forwarding URL shown by ngrok and append /mcp:

https://example.ngrok-free.app/mcp

The local inspection UI is normally available at http://127.0.0.1:4040. It can expose request details, so keep it local and do not share it publicly.

Connect a remote MCP client

Use the public HTTPS URL as an HTTP/Streamable HTTP MCP server:

{

"mcpServers": { "filesystem": { "transport": "http", "url": "https://your-public-host.example/mcp" } } }

Test both endpoints after the tunnel starts:

curl https://your-public-host.example/health

curl -i https://your-public-host.example/mcp

A non-200 response from a plain `G