mcp-readonly-fs

Read-only MCP filesystem server over allowlisted roots with realpath containment, deny globs on real paths, size and binary caps, and readOnlyHint tools

Problem

Giving an agent file access through a general filesystem server exposes write tools, secrets such as .env files, and paths outside the intended folders, reachable through traversal, symlinks or Windows path quirks. Many setups only need read access to a few directories. This package exposes four read-only MCP tools (list_directory, read_file, search_files, stat) over allowlisted roots. Path resolution is pure and tested separately from the MCP layer. The threat model is in docs/SECURITY.md.

Related MCP server: chatgpt-file-mcp

Install

npm install @trysac/mcp-readonly-fs

Requires Node.js 20 or newer. The package ships ES modules with TypeScript declarations. Runtime dependencies are @modelcontextprotocol/sdk (^1.23.0) and zod (^4.1.0).

Usage

import { createPolicy, createReadonlyFsServer } from "@trysac/mcp-readonly-fs";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const policy = await createPolicy({ roots: ["./docs"] });
const server = createReadonlyFsServer(policy, {
  onEvent: (e) => console.error(e.tool, e.ok, e.code),
});
await server.connect(new StdioServerTransport());

createPolicy throws PolicyError when a root does not exist or is not a directory.

Command line

src/cli.ts exports run(argv, io), which parses the flags below and serves over stdio. It is not re-exported by the package entry point and the package declares no bin entry.

--root DIR            # repeatable, required
--deny GLOB           # extra deny glob, added to the defaults
--max-file-bytes N    # default 1 MiB
--max-results N       # default 200

Exit codes: 0 success, 1 runtime server failure, 2 usage, IO or parse errors.

API

Tool error codes returned by the tools: OUTSIDE_ROOT, DENIED, NOT_FOUND, TOO_LARGE, BINARY, INVALID_PATH, NOT_A_FILE, NOT_A_DIRECTORY. An error result has isError: true and text ERROR <CODE>: <requested path>, truncated to 200 characters. It never contains the resolved real path.

Tools

All tools are annotated readOnlyHint: true and openWorldHint: false.

Limits and options

Paths are limited to 4096 characters. Roots: 1 to 64 directories. createPolicy replaces the default deny list when deny is given; the CLI --deny option adds to the defaults. Content search reads at most 64 MiB in total per call.

Why not server-filesystem

The reference server-filesystem MCP server ships write tools and has no deny list. This package exposes only read operations and hides secret-like paths by default.

Development

npm install
npm run check   # lint, format, types, tests with coverage, docs, secrets

See AGENTS.md for the full command list and CONTRIBUTING.md for the workflow.

Security

The threat model, the defended and undefended cases, and the limits are described in docs/SECURITY.md.

License

MIT © 2026 Miguel Gomez