fs-mcp-rs

一个快速、可配置的 Model Context Protocol（MCP）文件系统服务，使用 Rust 编写。

fs-mcp-rs 为 MCP 客户端提供一组精简的文件系统工具，同时将访问范围限制在操作员选定的目录内。它没有隐式文件系统根目录、内置个人路径或默认可写目录。只有提供配置文件后，服务才会启动。

为什么只用一个 crate？

对外发布的是一个 crate 和一个可执行文件，二者均命名为 fs-mcp-rs。协议、策略、文件系统、搜索和设置组件仍作为独立的 Rust 模块保留在该 crate 中。这让安装过程更简单：

cargo install fs-mcp-rs

用户无需安装或了解一系列内部 crate。基准测试运行器仍是仅用于开发的工作区成员，不包含在 crates.io 软件包中。

功能

• 通过 JSON-RPC HTTP POST 和按行分隔的 STDIO（stdin/stdout）提供 MCP。
• 通过 npx fs-mcp-rs 实现零安装运行。
• 显式允许一个或多个文件系统根目录（通过 CLI 位置参数或 TOML 配置）。
• 只读模式，适用于安全部署。
• 可选的写入、移动、编辑、创建目录和删除操作。
• 对读取、写入、搜索结果和并发数设定上限。
• 字面内容和正则表达式内容搜索。
• 支持 .gitignore，并可配置隐藏文件处理方式。
• 默认禁用符号链接遍历。
• 原子文件替换和 BLAKE3 哈希。
• 可选的任意终端命令执行，并限制执行时间和输出量。
• 持久终端会话，支持增量输出游标、长轮询、stdin、进程树终止、保留期限和有界缓冲区。
• 简洁的工具执行日志（[OK] / [WARN]）。
• 不进行遥测，也不会自动发现网络资源。

要求

• 使用 npx 执行需要 Node.js（v18+），或从源代码构建需要 Rust 1.85+。
• 能通过 STDIO JSON-RPC 或 Streamable HTTP/JSON-RPC 端点连接的 MCP 客户端。
• 配置文件，或传递给服务的显式根路径。

安装

通过 npx（无需安装）

使用 npx，即可轻松通过任何 MCP 客户端（例如 Claude Desktop 或 Cursor）运行 fs-mcp-rs：

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

npm 软件包会自动下载适用于你操作系统和架构的预编译二进制文件（Windows x64、Linux x64、macOS x64/arm64）。

从 crates.io 安装

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

从源代码构建

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

在类 Unix 系统上，可执行文件位于 target/release/fs-mcp-rs；在 Windows 上则位于 target\release\fs-mcp-rs.exe。

创建配置

将 configs/example.toml 复制到合适的位置并进行编辑。该服务有意不设置默认配置文件路径：

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

Windows PowerShell：

Copy-Item configs\example.toml fs-mcp-rs.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 = ["C:\\Users\\Alice\\Projects", "D:/Shared/Documentation"]

相对根路径将相对于配置文件所在目录解析，而不是相对于任意进程工作目录。

配置参考

[server]

• host：要绑定的 IP 地址。除非远程客户端确实需要访问，否则请保留 127.0.0.1。
• port：/health 和 /mcp 使用的 TCP 端口。
• max_concurrency：一次最多处理的 MCP 请求数。
• max_io_concurrency：同时运行的非搜索文件系统任务数上限。
• log_tools：是否打印简洁的工具执行日志（[OK] / [WARN]）（默认值：true）。

[filesystem]

• roots：非空的允许目录列表。每个请求的路径都必须解析到其中一个目录内。
• read_only：设为 true 时，所有会修改内容的工具调用都会被拒绝。
• max_write_bytes：write_file 或 edit_text 生成内容允许的最大字节数。
• follow_links：是否允许跟随包含符号链接的路径。除非已评估其影响，否则请保持为 false。

[search]

• max_results：一次搜索最多返回的匹配项数。
• max_concurrency：同时运行的搜索任务数上限。
• worker_threads：每次搜索用于遍历文件系统的线程数。
• regex_cache_capacity：内存中缓存的已编译搜索模式数量；设为 0 可禁用缓存。
• include_hidden：是否包含隐藏文件和目录。
• respect_gitignore：遍历目录时是否应用 Git 忽略文件。

[terminal]

• enabled：是否开放命令执行。禁用时，run_command 会返回工具错误。
• max_concurrency：同时运行的终端命令数上限。
• default_timeout_ms：调用未指定超时时使用的超时时间。
• max_timeout_ms：调用可请求的最大超时时间。
• max_output_bytes：每个终端会话保留的标准输出和标准错误合计字节数上限。较早的输出会被移除，并报告为已丢弃或截断。
• max_read_bytes：一次 terminal_read 调用返回的最大输出字节数。
• max_wait_ms：一次 terminal_read 调用的长轮询时长上限。
• session_retention_ms：已完成的会话及其输出在自动清理前可供读取的时长。

run_command 在 Windows 上通过 cmd.exe 执行任意命令，在 GNU/Linux 和 macOS 上通过 /bin/sh 执行。它带有破坏性和开放世界 MCP 注解，以便兼容的提供方显示警告。启用后，命令将拥有运行该服务的操作系统账户的全部权限；文件系统根目录和只读模式不会对终端命令进行沙箱隔离。

不接受未知字段和取值为零的安全限制。这样可以捕获拼写错误的设置，而不是将其静默忽略。

启动服务

位置参数根路径（快速入门）

直接在命令行中指定允许访问的文件系统目录以启动：

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

如果未传入配置文件或位置参数根路径，fs-mcp-rs 会使用限定在当前工作目录内的默认设置。

使用配置文件

显式传入配置文件：

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

也可以使用环境变量：

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

传输模式（STDIO 与 HTTP）

• STDIO 模式：当标准输出和标准输入为非交互式管道时（例如作为 MCP 子进程启动），或传入 --stdio 时自动启用。结构化日志会写入 stderr，以确保 stdout 保持干净，用于传输按行分隔的 JSON-RPC 消息。
• HTTP 模式：交互式执行期间默认启用。在配置的主机和端口上监听 /health 和 /mcp 端点。

检查 HTTP 健康状态：

curl http://127.0.0.1:8000/health

预期响应：

ok

MCP 端点为：

http://127.0.0.1:8000/mcp

同时启动服务和隧道

run 子命令始终以 HTTP 模式启动 MCP 服务，并可在同一进程生命周期内管理 ngrok、Cloudflare Quick Tunnel 或 zrok 公共共享：

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

这些提供商互斥。在 Windows 上，隧道默认会在新控制台中打开。使用 --tunnel-window hidden 可避免单独显示控制台，同时让生成的 URL 保留在当前终端中；也可以使用 --tunnel-window inherit 正常附加。在 Linux 和 macOS 上，new 会继承当前终端，因为创建终端窗口取决于桌面环境。每个提供商都支持重复指定额外参数，并可显式指定可执行文件路径：

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

停止 MCP 服务时也会停止隧道进程。现有调用方式（如 fs-mcp-rs [PATHS]、fs-mcp-rs --config FILE 和 fs-mcp-rs serve）保持不变。之前的 --ngrok-window 拼写仍是 --tunnel-window 的别名。

通过安全隧道公开服务

若要通过远程 MCP 客户端进行测试，请让 fs-mcp-rs 绑定到 loopback 地址，并通过隧道公开。先启动服务：

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

创建隧道前，先验证本地端点：

curl http://127.0.0.1:8000/health

注意

公共隧道 URL 会让远程客户端能够访问配置允许使用的工具和文件系统根目录。请先设置 read_only = true，仅授权范围严格受限的根目录，切勿公开机密，并在不再需要时停止隧道。Quick Tunnel 用于开发，而非永久生产托管。

Cloudflare Tunnel

安装 cloudflared，然后创建临时 Quick Tunnel：

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

cloudflared 会打印一个类似 https://random-name.trycloudflare.com 的临时 URL。在 URL 后追加 /mcp，使用 MCP 端点：

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

若要使用稳定的主机名，请创建具名 Cloudflare Tunnel，将 DNS 主机名映射到该隧道，并将该主机名路由到 http://127.0.0.1:8000。对于长期运行的部署，请使用 Cloudflare Access 或其他身份验证层进行保护。

ngrok

安装 ngrok，根据账户要求验证其 CLI，然后启动 HTTP 隧道：

ngrok http 8000

使用 ngrok 显示的 HTTPS 转发 URL，并在末尾追加 /mcp：

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

本地检查界面通常可通过 http://127.0.0.1:4040 访问。该界面可能会暴露请求详情，因此请将其保留在本地，不要公开分享。

连接远程 MCP 客户端

使用公共 HTTPS URL，将其配置为 HTTP/Streamable HTTP MCP 服务：

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

隧道启动后，测试两个端点：

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

普通 GET /mcp 返回非 200 响应可能是正常的，因为 MCP 通信使用协议请求；关键是确保 /health 可访问，并且 MCP 客户端能够初始化会话。

生产环境托管

对于持久化部署，优先使用专用网络/VPN 或具名的身份验证隧道。使用专用的低权限账户和服务管理器运行 fs-mcp-rs，使其绑定到 loopback 地址，在隧道或反向代理处终止 TLS，限制客户端访问，固定配置文件路径，并监控日志。不要依赖未受保护的公共 URL 作为唯一的安全边界。

配置 MCP 客户端

fs-mcp-rs 可配置为本地 STDIO 子进程，或配置为 MCP 客户端（如 Claude Desktop、Cursor、VS Code 或 Windsurf）中的远程/本地 HTTP 服务。

选项 A：使用 npx 的 STDIO 传输（推荐用于 Claude / Cursor）

无需预先安装：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "fs-mcp-rs", "/path/to/allowed/directory"]
    }
  }
}

或者使用已安装的二进制文件并显式指定 --stdio：

{
  "mcpServers": {
    "filesystem": {
      "command": "fs-mcp-rs",
      "args": ["--stdio", "/path/to/allowed/directory"]
    }
  }
}

选项 B：HTTP 传输

将 fs-mcp-rs 作为长期运行的服务启动，然后将客户端指向 /mcp HTTP 端点：

{
  "mcpServers": {
    "filesystem": {
      "transport": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

没有身份验证或 TLS 时，请勿将 HTTP 端点公开给不可信网络。

可用工具

• list_directory：列出目录的直接子项。
• read_file：读取指定偏移量和长度的 UTF-8 字节范围。
• write_file：以原子方式创建或替换 UTF-8 文件。对于新的嵌套路径，请设置 createParents: true；服务器会在验证允许的根目录后，安全地创建缺失的父目录。默认值为 false。
• search_files：查找文件名包含指定字符串的路径。
• search_content：在文本文件中进行不区分大小写的字面值搜索或正则表达式搜索。
• get_capabilities：报告经过净化的有效限制、根目录、协议版本和已公布的工具。
• list_tree：返回有界、确定性、分页的扁平目录树。
• apply_patch：以原子方式应用经过验证的单文件统一文本差异；dryRun 不会修改任何内容。
• file_info：返回详细元数据以及可选的有界流式 BLAKE3 摘要。
• create_directory：创建一个目录；父目录必须已存在。
• remove：移除一个文件或空目录。
• hash_file：计算 BLAKE3 文件哈希。
• move：移动文件，不覆盖已存在的目标。
• edit_text：以原子方式替换指定数量的精确文本匹配项。
• terminal_start：启动持久命令并立即返回会话 ID。
• terminal_read：使用字节游标增量读取 stdout/stderr 事件；可选择长轮询以获取新输出。
• terminal_write：向运行中会话的 stdin 写入 UTF-8 数据。
• terminal_close_stdin：向运行中的会话发送 EOF。
• terminal_kill：终止会话的完整进程树。
• terminal_close：显式移除已完成的会话及保留的输出。
• run_command：执行任意 shell 命令，可选工作目录和超时时间；为保持向后兼容，会等待命令完成。

只读模式下，修改类工具仍会显示，但调用时会返回明确的工具错误。这样，同一客户端配置即可用于只读和可写部署。

安全模型

1. 每个可读取路径都会进行规范化，并检查是否位于配置的根目录内。
2. 每个写入目标都会通过其现有父目录进行检查。
3. 默认拒绝遍历符号链接。
4. 读取、写入、结果数量和工作线程并发数均有限制。
5. 写入时会先在目标目录中创建临时文件，再进行持久化。
6. edit_text 要求指定预期替换数量，以防意外进行大范围编辑。

建议的生产环境安全措施：

• 从 read_only = true 开始。
• 仅授权必要的最小范围；除非有明确理由，否则不要授权整个主目录或驱动器。
• 绑定到环回地址。
• 使用专用的低权限操作系统账户运行。
• 除非有需要，否则排除隐藏文件。
• 如需远程访问，请在服务前配置身份验证和 TLS。
• 备份可写根目录，并测试恢复流程。

如果其他进程能够在操作期间替换路径组件，文件系统检查仍可能受到操作系统竞态条件的影响。不要与不受信任的本地用户共享可写根目录。

新工具示例

无需探测路径即可发现有效限制：

{"name":"get_capabilities","arguments":{}}

列出确定性目录树的一页，并使用返回的游标继续：

{"name":"list_tree","arguments":{"path":".","depth":2,"include":["**/*.rs"],"exclude":["target/**"],"maxEntries":100,"cursor":null}}

在不修改目标的情况下验证单文件补丁：

{"name":"apply_patch","arguments":{"path":"README.md","patch":"--- a/README.md\n+++ b/README.md\n@@ -1 +1 @@\n-old\n+new\n","expectedBlake3":null,"dryRun":true}}

请求详细元数据和有界流式哈希：

{"name":"file_info","arguments":{"path":"README.md","includeHash":true}}

apply_patch 会拒绝二进制、多文件、创建/删除和重命名补丁。所有差异块要么全部以原子方式应用，要么一个都不应用。它会保留目标文件现有的 LF 或 CRLF 换行约定以及末尾换行状态。dryRun 会执行完整验证，但绝不写入任何内容，包括只读模式下也是如此。

树和补丁限制配置参考

以下可选 [filesystem] 字段具有经过验证的默认值，因此现有配置文件仍可正常加载：

字段	默认值	限制
tree_max_depth	8	正整数，表示最大递归深度
tree_max_entries	1000	正整数，表示每页返回的最大条目数
tree_max_warnings	32	正整数，表示跳过条目警告的最大数量
patch_max_bytes	1048576	正整数，表示统一差异输入的最大字节数
patch_preview_bytes	16384	正整数，且不得大于 patch_max_bytes

list_tree 使用搜索的隐藏文件和 Git 忽略设置。游标是不透明的，并与规范根目录、深度和筛选条件绑定。每个请求的路径仍会经过 Policy；这些工具不会削弱根目录隔离、只读强制措施或符号链接限制。

从 stat 迁移

file_info 替代了之前公开的 stat 工具。stat 不再公布或分发。客户端应迁移到 file_info；只有在需要 BLAKE3 摘要时才设置 includeHash。

日志记录

结构化追踪日志

所有结构化追踪日志都会输出到 stderr，以确保在 STDIO 模式下运行时，stdout 保持干净，仅用于 JSON-RPC 2.0 帧。设置 RUST_LOG 可控制详细程度：

RUST_LOG=info fs-mcp-rs --config ./fs-mcp-rs.toml

仅在排查问题时使用 debug，因为诊断输出中可能会出现路径。

工具调用执行日志

当 log_tools = true（默认值）时，fs-mcp-rs 会为每次工具调用记录一行摘要：

• 成功：[OK] read_file src/main.rs (3 ms)
• 警告/错误：[WARN] read_file outside/allowed/path - OUTSIDE_ALLOWED_ROOT: path outside allowed roots (0 ms)

可在 TOML 配置的 [server] 下禁用工具日志：log_tools = false。

开发和发布验证

发布前运行完整的本地检查：

cargo fmt --all -- --check
cargo check --workspace --all-targets
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo publish --dry-run -p fs-mcp-rs

在 Windows 上，scripts\build.cmd 会运行相同的检查。持续集成（.github/workflows/ci.yml）会在 Ubuntu、macOS 和 Windows 运行器上执行格式检查、lint 和测试。GitHub Actions 发布工作流（.github/workflows/release.yml）会为所有主流平台构建预编译二进制归档，并与 npm 包一同发布。

基准测试方法见 BENCHMARKS.md。性能声明应附上原始结果、机器详情、配置和提交哈希。

许可证

Copyright (C) 2026 nihmadev ([email protected])。

根据 GNU GPL version 3 or any later version（GPL-3.0-or-later）授权。请参阅 LICENSE 和 https://www.gnu.org/licenses/gpl-3.0.html 上的官方许可证文本。