Bounded Filesystem Mcp

A fork of the Filesystem MCP server where every tool result has a size limit. Large files are read in windows instead of being returned in one piece.

Provenance

Vendored from modelcontextprotocol/servers, tag 2026.1.14 (commit 3e805376da81c063c2798410906b5fd134334a43), directory src/filesystem. This repository's history starts from that snapshot. Upstream is MIT licensed, copyright Anthropic, PBC; see LICENSE.

lib.ts, path-validation.ts, path-utils.ts, roots-utils.ts and their tests are unchanged from upstream (only __tests__/structured-content.test.ts is adapted, see below), so they can be synced by copying the files. The changes live in index.ts (tool registration) and the new bounded.ts.

Differences from upstream

• Result cap. A text result longer than the cap (default 50,000 characters) keeps its first 50,000 characters, never splitting a surrogate pair. A notice is added on its own line:

  [Result truncated: showing characters 1-50,000 of 1,234,567. Call again with offset=50000 to continue.]
  

  Tools that cannot page say how to narrow the request instead, for example:

  [Result truncated: showing characters 1-50,000 of 812,345. To see the rest, narrow the request: pass a deeper path, or add excludePatterns.]
  

• Paged reads. read_text_file and read_file take offset and limit, both counted in characters. Follow the offset in each notice to walk the whole file; the last window has no notice. The file is streamed and only the window is kept in memory. head and tail work as before, but cannot be combined with offset or limit.
• Capped listings. read_multiple_files, directory_tree, search_files, list_directory, list_directory_with_sizes and edit_file's diff all use the cap. read_multiple_files caps the combined text, and its notice says how many of the requested files were included in full. It reads the files one after another rather than in parallel.
• Media size limit. read_media_file refuses files over 5 MB (5,242,880 bytes) with an error naming the file size and the limit. It checks the size before reading any bytes.
• Plain text results. Tools have no outputSchema and return no structuredContent, only content blocks. Hosts that prefer structuredContent would otherwise see the text JSON-escaped and the payload doubled, so a capped result would not be the size the cap promises.
• The server reports itself as bounded-filesystem in initialize. Tool names and existing parameters are unchanged.

"Characters" here means UTF-16 code units, the same as a JavaScript string's length.

Options

Flag	Environment variable	Default	Meaning
--max-result-chars <n>	BOUNDED_FS_MAX_RESULT_CHARS	50000	Largest text result, in characters, before the truncation notice
--max-media-bytes <n>	BOUNDED_FS_MAX_MEDIA_BYTES	5242880	Largest file read_media_file will return

A flag wins over its environment variable. Both flags also accept the --flag=<n> form. Everything else on the command line is an allowed directory:

bunx [email protected] --max-result-chars 40000 /path/to/dir1 /path/to/dir2

Features

• Read/write files
• Create/list/delete directories
• Move files/directories
• Search files
• Get file metadata
• Dynamic directory access control via Roots

Directory Access Control

The server uses a flexible directory access control system. Directories can be specified via command-line arguments or dynamically via Roots.

Method 1: Command-line Arguments

Specify Allowed directories when starting the server:

bounded-filesystem-mcp /path/to/dir1 /path/to/dir2

Method 2: MCP Roots (Recommended)

MCP clients that support Roots can dynamically update the Allowed directories.

Roots notified by Client to Server, completely replace any server-side Allowed directories when provided.

Important: If server starts without command-line arguments AND client doesn't support roots protocol (or provides empty roots), the server will throw an error during initialization.

This is the recommended method, as this enables runtime directory updates via roots/list_changed notifications without server restart, providing a more flexible and modern integration experience.

How It Works

The server's directory access control follows this flow:

1. Server Startup

   • Server starts with directories from command-line arguments (if provided)
   • If no arguments provided, server starts with empty allowed directories

2. Client Connection & Initialization

   • Client connects and sends initialize request with capabilities
   • Server checks if client supports roots protocol (capabilities.roots)

3. Roots Protocol Handling (if client supports roots)

   • On initialization: Server requests roots from client via roots/list
   • Client responds with its configured roots
   • Server replaces ALL allowed directories with client's roots
   • On runtime updates: Client can send notifications/roots/list_changed
   • Server requests updated roots and replaces allowed directories again

4. Fallback Behavior (if client doesn't support roots)

   • Server continues using command-line directories only
   • No dynamic updates possible

5. Access Control

   • All filesystem operations are restricted to allowed directories
   • Use list_allowed_directories tool to see current directories
   • Server requires at least ONE allowed directory to operate

Note: The server will only allow operations within directories specified either via args or via Roots.

API

Tools

• read_text_file

  • Read complete contents of a file as text, or a window of it
  • Inputs:
    • path (string)
    • head (number, optional): First N lines
    • tail (number, optional): Last N lines
    • offset (integer, optional): Character position to start from (default 0)
    • limit (integer, optional): Number of characters to return, clamped to the result cap
  • Always treats the file as UTF-8 text regardless of extension
  • Cannot specify both head and tail simultaneously, or combine either with offset/limit
  • Results over the cap end with a notice giving the offset to continue from
  • read_file is the deprecated alias and behaves the same

• read_media_file

  • Read an image or audio file
  • Inputs:
    • path (string)
  • Streams the file and returns base64 data with the corresponding MIME type
  • Files over --max-media-bytes (default 5 MB) return an error without being read

• read_multiple_files

  • Read multiple files simultaneously
  • Input: paths (string[])
  • Failed reads won't stop the entire operation
  • The combined text is capped; the notice says how many files were included in full

• write_file

  • Create new file or overwrite existing (exercise caution with this)
  • Inputs:
    • path (string): File location
    • content (string): File content

• edit_file

  • Make selective edits using advanced pattern matching and formatting
  • Features:
    • Line-based and multi-line content matching
    • Whitespace normalization with indentation preservation
    • Multiple simultaneous edits with correct positioning
    • Indentation style detection and preservation
    • Git-style diff output with context
    • Preview changes with dry run mode
  • Inputs:
    • path (string): File to edit
    • edits (array): List of edit operations
      • oldText (string): Text to search for (can be substring)
      • newText (string): Text to replace with
    • dryRun (boolean): Preview changes without applying (default: false)
  • Returns detailed diff and match information for dry runs, otherwise applies changes
  • Best Practice: Always use dryRun first to preview changes before applying them

• create_directory

  • Create new directory or ensure it exists
  • Input: path (string)
  • Creates parent directories if needed
  • Succeeds silently if directory exists

• list_directory

  • List directory contents with [FILE] or [DIR] prefixes
  • Input: path (string)

• list_directory_with_sizes

  • List directory contents with [FILE] or [DIR] prefixes, including file sizes
  • Inputs:
    • path (string): Directory path to list
    • sortBy (string, optional): Sort entries by "name" or "size" (default: "name")
  • Returns detailed listing with file sizes and summary statistics
  • Shows total files, directories, and combined size

• move_file

  • Move or rename files and directories
  • Inputs:
    • source (string)
    • destination (string)
  • Fails if destination exists

• search_files

  • Recursively search for files/directories that match or do not match patterns
  • Inputs:
    • path (string): Starting directory
    • pattern (string): Search pattern
    • excludePatterns (string[]): Exclude any patterns.
  • Glob-style pattern matching
  • Returns full paths to matches

• directory_tree

  • Get recursive JSON tree structure of directory contents
  • Inputs:
    • path (string): Starting directory
    • excludePatterns (string[]): Exclude any patterns. Glob formats are supported.
  • Returns:
    • JSON array where each entry contains:
      • name (string): File/directory name
      • type ('file'|'directory'): Entry type
      • children (array): Present only for directories
        • Empty array for empty directories
        • Omitted for files
  • Output is formatted with 2-space indentation for readability

• get_file_info

  • Get detailed file/directory metadata
  • Input: path (string)
  • Returns:
    • Size
    • Creation time
    • Modified time
    • Access time
    • Type (file/directory)
    • Permissions

• list_allowed_directories

  • List all directories the server is allowed to access
  • No input required
  • Returns:
    • Directories that this server can read/write from

Tool annotations (MCP hints)

This server sets MCP ToolAnnotations on each tool so clients can:

• Distinguish read‑only tools from write‑capable tools.
• Understand which write operations are idempotent (safe to retry with the same arguments).
• Highlight operations that may be destructive (overwriting or heavily mutating data).

The mapping for filesystem tools is:

Tool	readOnlyHint	idempotentHint	destructiveHint	Notes
read_text_file	true	–	–	Pure read
read_media_file	true	–	–	Pure read
read_multiple_files	true	–	–	Pure read
list_directory	true	–	–	Pure read
list_directory_with_sizes	true	–	–	Pure read
directory_tree	true	–	–	Pure read
search_files	true	–	–	Pure read
get_file_info	true	–	–	Pure read
list_allowed_directories	true	–	–	Pure read
create_directory	false	true	false	Re‑creating the same dir is a no‑op
write_file	false	true	true	Overwrites existing files
edit_file	false	false	true	Re‑applying edits can fail or double‑apply
move_file	false	false	false	Move/rename only; repeat usually errors

Note: idempotentHint and destructiveHint are meaningful only when readOnlyHint is false, as defined by the MCP spec.

Usage

MCP clients start the server over stdio:

{
  "mcpServers": {
    "filesystem": {
      "command": "bunx",
      "args": [
        "[email protected]",
        "/Users/username/Desktop",
        "/path/to/other/allowed/dir"
      ]
    }
  }
}

npx -y [email protected] <dirs...> works the same way.

Build

npm install
npm run build
npm test

License

MIT. The upstream code is copyright Anthropic, PBC; the changes in this fork are copyright Shivam Singh. See LICENSE.