MCP Server
Filesystem MCP Server
Official MCP reference server providing controlled filesystem operations with dynamic directory access control via command-line arguments or MCP Roots protocol
What is Filesystem MCP Server?
The Filesystem MCP Server is a Node.js reference implementation maintained by the Model Context Protocol organization that enables AI assistants to perform filesystem operations within strictly defined boundaries. The server implements both traditional command-line argument-based directory allowlisting and the modern MCP Roots protocol, which allows clients to dynamically update allowed directories at runtime without server restart. When clients support the roots protocol, they send roots/list requests during initialization and can issue notifications/roots/list_changed updates to modify permissions on the fly. The server exposes 18 tools including read_text_file, write_file, edit_file with advanced pattern matching, create_directory, move_file, search_files with glob patterns, and directory_tree for recursive structure visualization. All tools include MCP ToolAnnotations that categorize operations as read-only, idempotent, or destructive, helping clients make informed decisions about tool invocation. The server sets openWorldHint: false on every tool to indicate it only accesses the local filesystem within allowed directories, never reaching external networks.
Key capabilities
Dynamic Directory Access Control via MCP Roots Protocol
Implements the MCP Roots protocol allowing clients to update allowed directories at runtime through roots/list requests during initialization and notifications/roots/list_changed updates, replacing static command-line arguments with dynamic permission management.
Advanced File Editing with Pattern Matching and Dry Run
The edit_file tool supports multi-line content matching with whitespace normalization, indentation preservation, multiple simultaneous edits, and Git-style diff output, with dryRun mode to preview changes before applying them.
ToolAnnotations for Read-Only and Destructive Operations
Every tool includes MCP ToolAnnotations specifying readOnlyHint, idempotentHint, and destructiveHint, enabling clients to distinguish safe read operations from write capabilities and identify destructive actions like write_file overwrites or move_file deletions.
Sandboxed Filesystem Access with Docker Volume Mounting
Supports Docker deployment with bind mounts to /projects directory, allowing read-only mounts via ro flag and ensuring the server can only access explicitly mounted directories, enforcing strict sandboxing for security-sensitive environments.
Use cases
Project-Aware Code Editing with Workspace Boundaries
AI coding assistants can read, edit, and refactor code within project directories using edit_file's pattern matching to update imports, rename symbols, or apply transformations while respecting workspace boundaries defined by Roots protocol.
Safe File Modifications with Dry Run Preview
Before applying potentially destructive edits, developers can use edit_file with dryRun: true to see Git-style diffs showing exact changes, indentation adjustments, and match locations, ensuring AI modifications match expectations before committing.
Codebase Navigation and Search with Glob Patterns
AI assistants use search_files with glob patterns to find configuration files, locate specific imports, or discover test files, combined with directory_tree for structural understanding and list_allowed_directories to confirm access boundaries.
Docker-Isolated Filesystem Access for CI/CD
Automated workflows can run the server in Docker with specific directories mounted to /projects, ensuring AI operations during build or test phases can only access designated paths, preventing accidental modifications to system files.
MCP capabilities
Tools
read_text_file
write_file
edit_file
search_files
Connection and auth
- Node.js runtime for NPX execution or Docker for containerized deployment
- At least one allowed directory specified via command-line args or client Roots support
- MCP client with roots protocol capability for dynamic directory updates
Client configuration
Claude Desktop
{
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/path/to/allowed/directory"
]
}