Filesystem MCP Server

Reads file contents from the local filesystem with configurable path allowlisting and denial patterns. Implements a security model that validates all requested paths against configured allow/deny rules before filesystem access, preventing directory traversal and unauthorized access to sensitive files. Uses MCP's resource-based architecture to expose files as queryable resources with metadata.

Writes content to files with configurable overwrite behavior and atomic write semantics. Supports creating new files, appending to existing files, or refusing to overwrite based on configuration. Implements write operations through MCP tools that validate target paths against the same security model as reads, ensuring writes respect configured access boundaries.

Lists directory contents recursively with configurable filtering by file type, name patterns, and depth limits. Implements depth-first or breadth-first traversal through the filesystem, applying allow/deny patterns at each directory level to prevent traversal into restricted paths. Returns structured metadata (file type, size, modification time) for each entry, enabling LLMs to understand directory structure without reading all files.

Moves or renames files within the filesystem while validating both source and destination paths against configured access control rules. Implements atomic move operations that ensure source and destination are both within allowed paths before executing the filesystem operation. Prevents moving files outside the sandboxed directory tree or into restricted locations.

Deletes files from the filesystem with configurable safety policies such as requiring explicit confirmation, preventing deletion of critical files, or enforcing trash/archive patterns instead of permanent deletion. Validates deletion targets against access control rules and optional deny-lists of protected files. Provides structured feedback on deletion success or policy violations.

Searches for files by name, path, or content patterns using glob, regex, or literal string matching. Implements search as an MCP tool that traverses allowed directories, applies filters, and returns matching file paths with optional context snippets. Respects path access control rules, preventing search results from exposing restricted files. Supports limiting search scope by directory, file type, or size.

Exposes all filesystem operations (read, write, move, delete, list, search) through the MCP Tools primitive with JSON schema definitions for each operation. Implements function calling by mapping MCP tool invocations to filesystem operations, with automatic parameter validation against the schema. Supports multiple transport mechanisms (stdio, HTTP, SSE) for client-server communication, allowing LLMs and other MCP clients to invoke filesystem tools through a standardized protocol.

Implements a declarative access control model using allow and deny patterns (glob, regex, or literal paths) that are evaluated at tool invocation time. Administrators configure which paths are accessible to LLMs and which are forbidden, with deny patterns taking precedence over allow patterns. Patterns are evaluated against absolute paths, preventing bypass through relative paths or symlinks. Access control is enforced uniformly across all filesystem operations (read, write, move, delete, list, search).

Exposes files as MCP Resources with metadata (path, size, modified time, encoding) queryable by clients without requiring full file reads. Implements the MCP Resources primitive to allow LLMs to discover and inspect files before deciding whether to read them. Resources are filtered by the same access control rules as tools, preventing exposure of restricted files in resource listings.

Implements structured error handling through MCP's error response format, returning detailed error messages and error codes for filesystem operations. Errors include context about why an operation failed (e.g., 'access denied: path not in allow list', 'file not found', 'permission denied'). Errors are serialized as MCP error responses, allowing clients to handle failures programmatically and provide meaningful feedback to users.