Filesystem

What Filesystem does

Filesystem connects an MCP client to local files and directories through a Node.js process. It supports reading text, returning binary or media content, writing files, applying targeted edits, creating and listing directories, moving files, searching with glob-style patterns, inspecting directory trees, and retrieving file metadata.

Every operation is checked against an allowed-directory list. This boundary applies to reads as well as changes, so the server cannot operate outside the directories made available to it. At least one allowed directory is required for useful operation.

How it works

The recommended access-control method passes directories as command-line arguments when the server starts:

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

The server communicates over stdio and supports both the 2026-07-28 protocol flow and 2025-era clients that use the initialize handshake. For the newer flow, the command-line directories are the complete allow-list. A server started without directories therefore rejects tool calls because no paths are permitted.

A 2025-era client with Roots support can provide or replace the allowed directories at runtime. The server waits for initial Roots data and for subsequent updates before checking affected tool calls, preventing operations from running against a directory that has just been withdrawn. Roots are deprecated for the 2026-07-28 protocol. Clients without Roots support continue using the command-line directories; if neither command-line directories nor usable Roots are available, initialization fails.

Setup and configuration

The package is published as @modelcontextprotocol/server-filesystem. Start its executable with one or more directories that the agent may access. Supplying multiple paths creates a shared allow-list for the connection. The list_allowed_directories tool reports the directories currently in force.

Command-line paths are the portable configuration because they work across protocol versions. With a 2025-era Roots-capable client, client-provided Roots replace all server-side command-line directories once they are loaded. An update containing no valid Roots revokes access until a valid root is exposed again, provided Roots had previously been applied.

Tools and capabilities

• Read complete UTF-8 text files, or request only the first or last lines.
• Read multiple files in one operation; failed individual reads do not stop the whole request.
• Return images and audio as typed base64 content, with other binary data represented as embedded resources.
• Create or overwrite files and create directories, including missing parent directories.
• Apply multiple line- or multi-line edits with whitespace normalization, indentation preservation, line-ending preservation, and Git-style diffs.
• Preview edits with dryRun before changing a file.
• List directory contents, optionally including sizes, totals, and sorting by name or size.
• Move or rename files and directories, with an error when the destination already exists.
• Search recursively with include and exclude glob patterns, build a JSON directory tree, and retrieve size, timestamps, and file-type metadata.

Limitations and notes

Text reads always interpret content as UTF-8 regardless of the file extension. read_text_file accepts either head or tail, but not both. File overwrites happen in place, preserving the inode, creation time, hard links, and permissions; they are not crash-atomic, so an interrupted write can leave partial content. Read-only files are refused rather than replaced. edit_file is designed for selective changes, and using its dry-run mode first is recommended.

Operations remain confined to the active allowed directories. A connection with an empty allow-list cannot perform filesystem work.