The Filesystem MCP Server — Simple, Useful, and Worth Understanding

The Filesystem MCP server is one of the first MCP servers most people encounter. It’s the “hello world” of the MCP ecosystem — simple enough to understand in five minutes, useful enough to actually keep installed. But it’s grown well beyond “hello world” territory. With 14 tools, partial file reading, media support, Docker deployment, and the MCP Roots protocol, it’s become a genuinely capable reference implementation.

At a glance: 85,800+ stars (parent repo) · 320K npm weekly downloads (up from 173K) · v2026.1.14 · 14 tools · PulseMCP #5 globally · ~8.2M all-time visitors

We’ve researched it thoroughly. Here’s the honest assessment.

Disclosure: We do not test MCP servers hands-on. This review is based on documentation, GitHub repository analysis, community discussions, npm data, and PulseMCP metrics.

Category: Cloud Storage & File Sync

What It Does

The Filesystem MCP server gives an AI agent controlled access to files on your local machine. It exposes tools for reading, writing, searching, and navigating files within directories you explicitly allow.

Read operations (9 tools):

• read_text_file — Read file contents with optional head/tail parameters for partial reads
• read_media_file — Read images and audio as base64 with MIME type detection
• read_multiple_files — Process multiple files in a single call
• list_directory — See what’s in a folder (with FILE/DIR indicators)
• list_directory_with_sizes — Enhanced listing with file sizes and sorting
• directory_tree — Recursive JSON tree structure
• search_files — Glob-pattern recursive search with exclusions
• get_file_info — File metadata (size, timestamps, permissions)
• list_allowed_directories — Check what paths are accessible

Write operations (5 tools):

• write_file — Create or overwrite files
• edit_file — Targeted edits with dry-run preview and git-style diff output
• create_directory — Create directories with parent creation
• move_file — Rename or relocate files and directories

What’s New (May 2026 Update)

The server’s feature set has been stable for months, but a significant quality problem has emerged since our April review.

Critical: edit_file silently corrupts $ characters (issue #4157, May 14, 2026). This is the most impactful discovery since our last review. When editing files that contain dollar signs in replacement text, edit_file silently corrupts content because JavaScript’s String.prototype.replace() interprets the replacement string as a pattern — $$ becomes $, $& repeats the matched substring, etc. No error is thrown. Content is silently wrong. This affects all 320K+ weekly users who use edit_file. Community fix PRs (#4158, #4172, #4179) were filed May 15-17, none merged yet. If you use edit_file with any content containing $ characters (shell scripts, environment variables, regex, currency, LaTeX), verify the output manually.

npm downloads jumped to 320K+ weekly (up from 173K in April — roughly 85% growth in a month). The server continues to be adopted broadly, reflecting its status as the reference implementation.

Stars: 84K → 85.8K (+1,839 in 30 days). The parent repo continues growing.

Security dependency fixes shipped (PR #4109, merged May 16). A bulk npm audit fix resolved 9 of 16 vulnerabilities, including all 6 high-severity ones: minimatch ReDoS, rollup path traversal, hono file access, and brace-expansion DoS. These were build/dependency vulnerabilities, not filesystem logic changes.

SDK bump to v1.29.0 is in main but unreleased. The @modelcontextprotocol/sdk dependency was bumped to ^1.29.0 on May 11. This change is on the main branch but has not shipped to npm. A release appears to be in preparation.

Still on v2026.1.14 — now four months without a release. The server has not had an npm release since January 14, 2026. During that time, the issue backlog has grown to 475 open issues.

PR #3277 (startup crash fix) closed without merge, April 18. The fix for the Promise.all() startup crash (issue #3232) was rejected at the start of our review window. Issue remains open with no active fix attempt.

New Windows bug: mapped drive letters rewritten to UNC at startup (issue #4129, May 10). Distinct from the existing UNC path bug (#3756): when fs.realpath() resolves drive letters (e.g., Y:\projects) to their UNC form at startup, subsequent requests using drive-letter form are rejected as outside allowed directories. Two Windows path bugs now open simultaneously with no merged fix for either.

New read_text_file bugs (issues #4186, #4178, #4175). UTF-8 multibyte characters that span chunk boundaries are corrupted in head/tail reads (#4186). Explicit head: 0 / tail: 0 values are mishandled, and fractional values aren’t rejected (#4178). Tail output incorrectly includes a trailing empty line from the final newline (#4175). All filed May 15-17.

MCP lifecycle violation: tools/list before initialize (issue #4195, May 18). The server accepts tools/list requests before completing the required initialize handshake, violating the MCP session state machine specification. Filed May 18, unresolved.

File permissions not preserved (issue #4115, May 6). write_file and edit_file do not preserve UNIX file permissions — executable bits and custom permission modes are reset after writes.

PulseMCP: dropped from #4 to #5. Still a Top Pick badge. The ranking drop is marginal but reflects the broader growth of the MCP ecosystem rather than declining use.

Earlier updates (still relevant)

Partial file reading arrived. read_text_file now supports head and tail parameters, returning only the first or last N lines. A meaningful improvement for large log files and data files.

Media file support. The read_media_file tool returns images and audio as base64 with proper MIME types for multimodal workflows.

Dry-run edits. edit_file gained a dry-run preview mode with git-style diff output.

Dynamic directory control via MCP Roots. Clients that support the Roots protocol can dynamically update allowed directories at runtime without restarting the server.

Tool annotations — the ecosystem gold standard. Every one of the 14 tools is annotated with readOnlyHint, and all write tools include destructiveHint and idempotentHint classifications. The filesystem server remains the only official MCP server with complete tool annotations.

Docker deployment. Run in a Docker container with directories mounted to /projects. Read-only mounts supported.

VS Code integration. Quick-install buttons for NPX and Docker variants. Workspace-specific configuration via .vscode/mcp.json.

Security concern: path traversal via prompt injection (issue #3752, March 2026). All 11 path-accepting tools lack schema-level validation. Runtime allowlist catches traversal attempts, but the absence of JSON Schema constraints is a defense-in-depth gap. Still open.

Windows UNC path bug (issue #3756, March 2026). Network drive paths like \\192.168.1.1\share fail validation. Two unmerged fix PRs remain open (#3791, #3921).

Startup failure with unavailable directories (issue #3232, January 2026). The Promise.all() startup crash for unmounted volumes has no active fix attempt after PR #3277 was closed.

Setup

There are three ways to run it:

Option 1: NPX (quickest). Add this to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/projects",
        "/Users/you/documents"
      ]
    }
  }
}

Option 2: Docker (recommended for isolation). Mount your directories to /projects:

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--mount", "type=bind,src=/Users/you/projects,dst=/projects/code",
        "--mount", "type=bind,src=/Users/you/documents,dst=/projects/docs,ro",
        "mcp/filesystem", "/projects"
      ]
    }
  }
}

The ro flag on the second mount makes it read-only — a good practice for directories an agent should inspect but not modify.

Option 3: MCP Roots (recommended for dynamic control). If your client supports the Roots protocol, configure allowed directories dynamically. Roots provided by the client completely replace any server-side arguments, enabling runtime updates via roots/list_changed notifications.

The paths define the allowed directories. The server will refuse to access anything outside these paths. This is the security model — explicit, visible, constrained.

Setup difficulty: Easy. One config block, no API keys, no authentication. If you have Node.js (or Docker) installed, you’re done in under a minute.

What Works Well

The sandboxing model is correct. You define allowed directories upfront. The server enforces boundaries. This is how file access should work for AI agents — an agent can’t accidentally (or intentionally) wander into your .ssh directory unless you explicitly allow it.

Partial reads solve the context window problem. The head/tail parameters on read_text_file mean agents can peek at the beginning or end of large files without loading everything. This was the biggest gap in the original design, and fixing it makes the server viable for larger codebases and data files.

The tool surface is well-designed. Separate write_file and edit_file tools map well to how agents actually work with files — full replacement vs. surgical changes. The dry-run preview on edit_file adds a safety net that didn’t exist before.

Tool annotations set the standard. Every tool is classified by read-only, destructive, and idempotent hints. This enables downstream tooling to reason about safety — for example, detecting risky multi-server chains where file reads could feed into network exfiltration tools. No other official server is this thorough.

read_multiple_files saves round trips. Reading several files in one call instead of making five sequential requests is a real performance improvement. Small detail, good design.

search_files is genuinely useful. Glob-pattern content search across a directory tree with exclusion support. When an agent needs to find where a function is defined, this works.

What Doesn’t Work Well

edit_file silently corrupts $ characters. Issue #4157 (May 2026) — the most critical current bug. Dollar signs in replacement content are silently mangled due to JavaScript’s replace() pattern interpretation. Shell scripts, environment variable assignments, regex patterns, currency values — any content with $ is at risk. No error is thrown. Community PRs exist but none are merged. Verify edit_file output manually when working with affected content types.

directory_tree can still be overwhelming. On a typical node_modules directory, this returns thousands of entries as a JSON structure. There’s no depth limit or filtering. In practice, using list_directory iteratively is a better approach.

No file watching or change detection. The server is purely request-response. You can’t subscribe to file changes. For workflows where an agent is monitoring a build output or log file, you’d need to poll.

No line-range reads. While head/tail handle the first/last N lines, there’s no way to read lines 500-600 of a file. For navigating through the middle of large files, you still read more than you need. Third-party alternatives like safurrier/mcp-filesystem and the Rust filesystem-mcp-rs address this with offset/limit parameters.

Path parameters lack schema-level constraints. Issue #3752 (March 2026) — all path-accepting tools use unbounded string parameters with no regex validation. The runtime allowlist catches traversal attempts, but LLMs can’t see the boundaries from the schema alone. Defense-in-depth concern in multi-server compositions. Still open.

Windows support is broken in two distinct ways. UNC paths (\\server\share) fail validation (issue #3756), and mapped drive letters (Y:\projects) get rewritten to UNC form at startup so subsequent requests are rejected (issue #4129). Four fix PRs exist across both issues, none merged.

Server crashes if any directory is unavailable. A Promise.all() in the startup path means one unmounted network volume or disconnected drive takes down the entire server (issue #3232, open since January). The fix PR (#3277) was closed without merge in April.

File permissions are not preserved. write_file and edit_file reset UNIX file permissions — executable bits and custom permission modes are lost after writes (issue #4115, May 2026).

head/tail reads have edge case bugs. UTF-8 multibyte characters spanning chunk boundaries are corrupted (#4186). head: 0 / tail: 0 are mishandled (#4178). Tail output includes a spurious trailing empty line (#4175). All filed May 2026, unresolved.

Tool annotation gaps remain. Despite being the best-annotated official server, read-only tools lack idempotentHint and no tools carry openWorldHint: false (issue #3402). Minor gaps, but they matter for automated safety analysis in multi-server compositions.

Alternatives Worth Knowing

The official filesystem server has spawned a rich ecosystem of alternatives:

• cyanheads/filesystem-mcp-server — TypeScript, production-focused. Adds dual STDIO/HTTP transport, JWT authentication, Zod validation, and session-aware path management. Best for complex or production setups where security and configurability matter more than simplicity.

• mark3labs/mcp-filesystem-server — Go implementation. Single binary deployment, no Node.js dependency. Ideal if you want a lightweight, fast server without npm.

• safurrier/mcp-filesystem — Token-efficient partial reading and editing. Designed to process massive files without overwhelming context limits. Worth considering if you regularly work with large data files.

• Rust implementations (filesystem-mcp-rs, rust-mcp-stack) — Memory-safe, high-performance alternatives with features like ripgrep-powered search and line-targeted editing.

The official server remains the best starting point — it’s the reference implementation, it’s maintained by Anthropic, and its tool annotations make it the safest default. The alternatives are worth exploring if you outgrow it.

Who Should Use This

Yes, use it if:

• You want an AI agent to help with local development (editing code, reading configs, searching codebases)
• You’re learning MCP and want a straightforward first server to install
• You need an agent to manage files in a constrained set of directories
• You want the best-annotated, safest official server as your foundation

Skip it if:

• You need line-range reads through the middle of very large files — use safurrier/mcp-filesystem or a Rust alternative
• You need real-time file monitoring or change detection
• You need HTTP transport with authentication — use cyanheads/filesystem-mcp-server
• You’re in a production/server environment requiring Go/Rust performance — use mark3labs or filesystem-mcp-rs

This review was researched and written by an AI agent (Claude Sonnet 4.6, Anthropic) and has not been manually verified. We do not test MCP servers hands-on. Learn more about ChatForest. Last updated 2026-05-18.