@modelcontextprotocol/server-filesystem

Provides controlled read access to filesystem resources through MCP protocol with configurable root directory constraints. Implements a whitelist-based access model where the server enforces directory boundaries, preventing path traversal attacks via normalization and validation of requested paths against allowed roots. Clients connect via stdio or HTTP transport and request file contents, which are streamed back through the MCP message protocol with size limits and encoding handling.

Recursively enumerates directory structures with configurable depth limits and filtering, returning hierarchical file listings with metadata (type, size, modification time). Uses filesystem stat calls to build tree representations and applies ignore patterns (e.g., .gitignore-style rules) to exclude files from enumeration. Supports both shallow single-level listings and deep recursive traversals with configurable max-depth to prevent performance degradation on large codebases.

Abstracts filesystem operations behind the Model Context Protocol (MCP), enabling any MCP-compatible client (Claude, custom agents, etc.) to invoke filesystem capabilities through standardized JSON-RPC messages over stdio, HTTP, or WebSocket transports. The server implements MCP resource and tool schemas that define available operations, their parameters, and response formats, allowing clients to discover capabilities via introspection and invoke them with type-safe argument passing.

Restricts filesystem access to one or more configured root directories through configuration-time specification of allowed paths. The server validates all requested file paths against these roots using path normalization (resolving .. and . components) and ensures requests cannot escape the sandbox via symlinks or path manipulation. Multiple roots can be configured to expose different project directories or mount points, each independently validated and isolated.

Reads file contents and streams them through the MCP protocol with automatic encoding detection and conversion. Handles both text files (UTF-8, ASCII, etc.) and binary files, with configurable size limits to prevent memory exhaustion from huge files. Implements chunked reading for large files and provides encoding metadata in responses, allowing clients to properly interpret file contents regardless of source encoding.

Defines filesystem paths as MCP resources with standardized schemas, enabling clients to discover available files and directories through MCP introspection. Resources are registered with URIs (e.g., filesystem://project/src/index.ts) and metadata, allowing clients to query what resources exist and their properties without making individual file requests. Implements MCP resource listing endpoints that return available resources with filtering and pagination support.