MCP Read File Server

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.