# mcp-read-file-server [Health: Active]

**Category:** 📂 File Systems  
**Repository:** https://github.com/hebulin/mcp-read-file-server  
**GitHub Stars:** 14  
**npm Downloads (last month):** 343  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mcp-read-file-server

## Description
加密环境文件操作 MCP 工具。当 Node.js 是加密软件白名单进程时，通过 fs 模块自动解密读写文件明文，替代 AI Agent 内置文件工具，适用于任何支持 MCP 协议的 Agent。

## Tools
Capabilities this server exposes over MCP:

- **read_file** — 严格读取UTF8；最多40万字符，完整读取时返回hash，截断时返回nextOffset。
- **read_files** — 批量严格读取UTF8，最多100个文件，总内容预算40万字符，逐项返回状态。
- **read_file_partial** — 字符/行分页。offset按去BOM后的UTF16单元计算，请使用nextOffset；行模式流式读取并返回nextLine。
- **write_file** — 写入或追加UTF8，暂存校验后提交，失败保留原文件；支持BOM/EOL、hash冲突检查、禁止覆盖和显式策略。
- **edit_file** — 单次或批量编辑互斥；全部匹配成功后暂存提交。支持dryRun预览、expectedHash/expectedMatches、换行兼容和限时正则。
- **search_files** — 按行搜索，支持literal/regex、include数组与花括号、隐藏项开关。单文件5MB，总输出40万字符，错误明确报告；正则限时执行。
- **find_files** — 按glob递归查找，支持花括号、字面括号路径、隐藏项及默认忽略开关。
- **list_directory** — 列目录的文件/目录/链接类型与元数据，支持分页。
- **file_info** — 查询大小/时间/链接；流式计算可读字节数及hash，不经文本解码。calculateHash=false可只查元数据。
- **create_directory** — 递归创建目录，受只读模式与allowedRoots约束。
- **copy_path** — 逐文件复制和验证。目标已有目录时放入其下；失败返回部分目标并保留源，不自动跟随链接。
- **move_path** — 复制验证后再删源，同路径不操作；同盘/跨盘使用相同校验流程。
- **remove_path** — 删除文件/目录或链接。recursive=false仅删空目录，dryRun仅预览；拒绝删除工作根/盘符根。
- **check_status** — 心跳不触发探测；可选文件前缀检查，只在expectedHash可信对照一致时确认内容，不凭能读取推断解密正常。
- **encryption_profile** — 查看自动探测和独立手工策略；首次调用会创建隔离探测样本与缓存。
- **refresh_profile** — 刷新自动探测缓存，保留手工protected/unsafe策略。
- **mark_extension** — 独立保存策略：protected保留受控写入，unsafe必须验证明文，clear清除手工覆盖；刷新与TTL不丢失标注。
- **inspect_write_strategy** — 检查写入策略：已有文件比较Node与外部读取视图，新建路径可在父目录创建探测样本；不修改目标文件。

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "mcp-read-file-server": {
    "command": "npx",
    "args": ["-y","mcp-read-file-server"]
  }
}
```

## Documentation

## What mcp-read-file-server does

mcp-read-file-server provides an MCP interface for file and directory operations. Its main use case is a workstation where file-encryption software treats Node.js as a trusted process but does not grant the same access to an AI agent. Node.js then performs the filesystem calls through `fs`, allowing the agent to work with the view available to that trusted process.

The server handles strict UTF-8 reads, partial reads by character or line, batch reads, text editing, searching, glob-based file discovery, directory listing, metadata inspection, directory creation, copying, moving, and removal. It also includes tools for inspecting and managing encryption-related write policies.

## How it works

The MCP connection uses standard stdio. The architecture places the agent in front of the Node.js process, with filesystem modules behind it. Reads are bounded: individual and aggregate responses have character limits, and pagination returns offsets or line positions for continuation.

Text writes and edits use temporary files, validation, backup renames, final checks, and rollback handling. Hash and expected-match options can detect concurrent changes. Copy and move operations validate files individually; moves remove sources only after verified copies. Locks cover paths and related directory trees across instances that share the same profile directory.

For encryption-aware writes, `auto` examines the target file or source state rather than assuming that Node.js readability proves editor compatibility. `preserve` uses controlled staging, while `plaintext` requires external-view validation. On Windows, built-in external readers include PowerShell, `pwsh`, `cmd`, `robocopy`, and `cscript` where available. External verification is not a claim about raw disk contents or encryption strength.

## Setup and configuration

The process requires Node.js 20 or newer and runs as an MCP stdio server. Claude Code, Cursor, Windsurf, Cline, Roo Code, Continue, and Zed can be configured to launch it through their MCP settings or configuration files. Other MCP-compatible agents can use the same stdio arrangement.

The Node.js process should be included in the encryption product's trusted-process or whitelist configuration when plaintext access depends on that status. `MCP_PROCESS_TIMEOUT_MS` controls the timeout for external readers and copy processes; its default is 5,000 milliseconds and the accepted range is 1–60,000. Encryption profiles are cached under the user's home directory, while manual extension policies are stored separately. A shared `MCP_PROFILE_DIR` allows instances to coordinate locks and profile data.

## Tools and capabilities

- `read_file`, `read_files`, and `read_file_partial` support bounded UTF-8 reads, batching, hashes, character pagination, and line streaming.
- `write_file` and `edit_file` support append or replace operations, BOM and EOL handling, dry runs, regular expressions, expected hashes, expected match counts, and protected commits.
- `search_files`, `find_files`, and `list_directory` cover line search, glob traversal, directory metadata, hidden entries, pagination, and bounded output.
- `file_info` reports metadata and can stream byte counts and hashes without text decoding.
- `create_directory`, `copy_path`, `move_path`, and `remove_path` apply root, read-only, link, overlap, validation, and partial-failure safeguards.
- `check_status`, `encryption_profile`, `refresh_profile`, `mark_extension`, and `inspect_write_strategy` expose status checks, automatic probing, persistent extension policies, and write-strategy previews.

## Limitations and notes

The server is not a general encryption bypass. Its results depend on what the trusted Node.js and external reader processes can observe. On Linux and macOS, external validation for explicit `plaintext` or manually marked `unsafe` writes is unavailable through the built-in readers. Windows `auto` writes can return `DISK_UNVERIFIED` when no suitable external reader is available.

Recursive deletion is bounded and is not an all-or-nothing tree transaction. Symbolic links are rejected for copy and move operations, and deletion protects work roots and filesystem roots. Unexpected termination between rename steps can leave backup or staging files that require inspection before manual recovery. Existing damaged or encrypted files are not repaired automatically.

_Full upstream README: https://allmcps.com/mcp/mcp-read-file-server/readme_