filesystem-mcp-server

Exposes local filesystem operations as standardized MCP resources and tools, allowing Claude and other MCP-compatible clients to read, list, and traverse directory structures without direct OS access. Implements the Model Context Protocol specification to bridge filesystem I/O into LLM context windows through a server-client architecture, enabling safe sandboxed file access with configurable permissions boundaries.

Provides recursive directory listing and file discovery capabilities through MCP tools, allowing clients to explore filesystem hierarchies, filter by file type/pattern, and retrieve metadata (size, modification time, permissions) for each entry. Implements efficient directory traversal using native OS APIs (fs.readdir, os.scandir) with optional depth limiting and pattern matching to prevent runaway queries on large directory trees.

Reads file contents through MCP tools with automatic encoding detection (UTF-8, ASCII, binary) and optional base64 encoding for binary files, allowing clients to safely retrieve and process file contents regardless of format. Uses native file I/O APIs with streaming support for large files and configurable size limits to prevent memory exhaustion or context window overflow.

Enables MCP clients to create, write, and modify files on the local filesystem through standardized MCP tools, with support for atomic writes, permission preservation, and optional backup creation before overwriting. Implements write operations using temporary file + rename pattern to ensure atomicity and prevent partial writes on failure, with configurable path restrictions to prevent directory traversal attacks.

Provides MCP tools for safe file and directory deletion with optional recursive directory removal, trash/recycle bin integration (where available), and configurable safety checks (confirmation prompts, size limits, pattern restrictions). Implements deletion using OS-native APIs with optional soft-delete to recycle bin rather than permanent removal, preventing accidental data loss from AI-generated commands.

Exposes file and directory metadata (size, modification time, creation time, permissions, ownership) through MCP tools, allowing clients to inspect file properties without reading contents. Uses native OS stat APIs to retrieve metadata efficiently with support for both POSIX and Windows permission models, enabling permission-aware operations and file age-based filtering.

Implements path validation and normalization within MCP tools to prevent directory traversal attacks (e.g., ../../../etc/passwd), symlink escapes, and invalid path constructs. Uses configurable path whitelisting/blacklisting with support for glob patterns, ensuring that all filesystem operations stay within designated safe directories and preventing access to sensitive system paths.

Exposes filesystem operations as standardized MCP resources and tools with JSON Schema definitions, allowing MCP clients to discover available operations, required parameters, and expected outputs through the MCP protocol's introspection mechanism. Implements schema generation that describes each filesystem operation (read, write, delete, list) with parameter types, constraints, and descriptions, enabling clients to build dynamic UIs or validate requests before sending.

Returns detailed file metadata including size, modification time, creation time, access time, permissions, owner, and file type (regular file, directory, symlink, etc.). Implements efficient stat calls without reading file content and returns metadata in a structured JSON format suitable for AI analysis and decision-making about file processing.

Implements the Model Context Protocol server-side message handling, including request/response routing, error handling, and transport abstraction (stdio, HTTP, or other transports). Handles MCP handshake, capability advertisement, and tool registration, allowing any MCP-compatible client (Claude, custom agents, IDE extensions) to discover and invoke filesystem tools. Manages concurrent requests and maintains protocol compliance.