fs-mcp-rs

<!-- mcp-name: io.github.nihmadev/fs-mcp-rs -->
# fs-mcp-rs

[![Crates.io](https://img.shields.io/crates/v/fs-mcp-rs?logo=rust&label=crates.io)](https://crates.io/crates/fs-mcp-rs)
[![docs.rs](https://img.shields.io/docsrs/fs-mcp-rs?logo=docs.rs&label=docs.rs)](https://docs.rs/fs-mcp-rs)
[![License](https://img.shields.io/crates/l/fs-mcp-rs?label=license)](LICENSE)
[![Rust 1.85+](https://img.shields.io/badge/rust-1.85%2B-orange?logo=rust)](https://www.rust-lang.org)
[![MCP](https://img.shields.io/badge/MCP-Streamable%20HTTP-6f42c1)](https://modelcontextprotocol.io)

[![English](https://img.shields.io/badge/lang-English-lightgrey)](README.md)
[![Русский](https://img.shields.io/badge/lang-Русский-blue)](README_RU.md)

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:

```console
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`:

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

```console
cargo install fs-mcp-rs
fs-mcp-rs --version
```

### From source

```console
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:

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

Windows PowerShell:

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

Minimal read-only configuration:

```toml
[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:

```toml
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:

```console
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:

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

Or use the environment variable:

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

PowerShell:

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

```console
curl http://127.0.0.1:8000/health
```

Expected response:

```text
ok
```

The MCP endpoint is:

```text
http://127.0.0.1:8000/mcp
```

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

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

Verify the local endpoint before creating a tunnel:

```console
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`](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/), then create a temporary Quick Tunnel:

```console
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:

```text
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`](https://ngrok.com/download), authenticate its CLI if required by your account, and start an HTTP tunnel:

```console
ngrok http 8000
```

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

```text
https://example.ngrok-fr