Filesystem

# Filesystem MCP Server Node.js server implementing Model Context Protocol (MCP) for filesystem operations. Published on npm as [`@modelcontextprotocol/server-filesystem`](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem). ## Features - Read/write files - Create/list/delete directories - Move files/directories - Search files - Get file metadata - Dynamic directory access control via [Roots](https://modelcontextprotocol.io/docs/learn/client-concepts#roots) ## Directory Access Control The server uses a flexible directory access control system. Directories can be specified via command-line arguments or dynamically via [Roots](https://modelcontextprotocol.io/docs/learn/client-concepts#roots). ### Method 1: Command-line Arguments Specify Allowed directories when starting the server: ```bash mcp-server-filesystem /path/to/dir1 /path/to/dir2 ``` ### Method 2: MCP Roots (Recommended) MCP clients that support [Roots](https://modelcontextprotocol.io/docs/learn/client-concepts#roots) can dynamically update the Allowed directories. Roots notified by Client to Server, completely replace any server-side Allowed directories when provided. **Important**: If server starts without command-line arguments AND client doesn't support roots protocol (or provides empty roots), the server will throw an error during initialization. This is the recommended method, as this enables runtime directory updates via `roots/list_changed` notifications without server restart, providing a more flexible and modern integration experience. ### How It Works The server's directory access control follows this flow: 1. **Server Startup** - Server starts with directories from command-line arguments (if provided) - If no arguments provided, server starts with empty allowed directories 2. **Client Connection & Initialization** - Client connects and sends `initialize` request with capabilities - Server checks if client supports roots protocol (`capabilities.roots`) 3. **Roots Protocol Handling** (if client supports roots) - **On initialization**: Server requests roots from client via `roots/list` - Client responds with its configured roots - Server replaces ALL allowed directories with client's roots - **On runtime updates**: Client can send `notifications/roots/list_changed` - Server requests updated roots and replaces allowed directories again 4. **Fallback Behavior** (if client doesn't support roots) - Server continues using command-line directories only - No dynamic updates possible 5. **Access Control** - All filesystem operations are restricted to allowed directories - Use `list_allowed_directories` tool to see current directories - Server requires at least ONE allowed directory to operate **Note**: The server will only allow operations within directories specified either via `args` or via Roots. ## API ### Tools - **read_text_file** - Read complete contents of a file as text - Inputs: - `path` (string) - `head` (number, optional): First N lines - `tail` (number, optional): Last N lines - Always treats the file as UTF-8 text regardless of extension - Cannot specify both `head` and `tail` simultaneously - **read_media_file** - Read a file and return it as a base64-encoded content block with its MIME type - Inputs: - `path` (string) - Streams the file and returns base64 data with the corresponding MIME type. Image and audio files are returned as `image`/`audio` content; any other file type is returned as an embedded `resource` (a valid MCP content block for arbitrary binary data) - **read_multiple_files** - Read multiple files simultaneously - Input: `paths` (string[]) - Failed reads won't stop the entire operation - **write_file** - Create new file or overwrite existing (exercise caution with this) - Inputs: - `path` (string): File location - `content` (string): File content - **edit_file** - Make selective edits using advanced pattern matching and formatting - Features: - Line-based and multi-line content matching - Whitespace normalization with indentation preservation - Multiple simultaneous edits with correct positioning - Indentation style detection and preservation - Git-style diff output with context - Preview changes with dry run mode - Inputs: - `path` (string): File to edit - `edits` (array): List of edit operations - `oldText` (string): Text to search for (can be substring) - `newText` (string): Text to replace with - `dryRun` (boolean): Preview changes without applying (default: false) - Returns detailed diff and match information for dry runs, otherwise applies changes - Best Practice: Always use dryRun first to preview changes before applying them - **create_directory** - Create new directory or ensure it exists - Input: `path` (string) - Creates parent directories if needed - Succeeds silently if directory exists - **list_directory** - List directory contents with [FILE] or [DIR] prefixes - Input: `path` (string) - **list_directory_with_sizes** - List directory contents with [FILE] or [DIR] prefixes, including file sizes - Inputs: - `path` (string): Directory path to list - `sortBy` (string, optional): Sort entries by "name" or "size" (default: "name") - Returns detailed listing with file sizes and summary statistics - Shows total files, directories, and combined size - **move_file** - Move or rename files and directories - Inputs: - `source` (string) - `destination` (string) - Fails if destination exists - **search_files** - Recursively search for files/directories that match or do not match patterns - Inputs: - `path` (string): Starting directory - `pattern` (string): Search pattern - `excludePatterns` (string[]): Exclude any patterns. - Glob-style pattern matching - Returns full paths to matches - **directory_tree** - Get recursive JSON tree structure of directory contents - Inputs: - `path` (string): Starting directory - `excludePatterns` (string[]): Exclude any patterns. Glob formats are supported. - Returns: - JSON array where each entry contains: - `name` (string): File/directory name - `type` ('file'|'directory'): Entry type - `children` (array): Present only for directories - Empty array for empty directories - Omitted for files - Output is formatted with 2-space indentation for readability - **get_file_info** - Get detailed file/directory metadata - Input: `path` (string) - Returns: - Size - Creation time - Modified time - Access time - Type (file/directory) - Permissions - **list_allowed_directories** - List all directories the server is allowed to access - No input required - Returns: - Directories that this server can read/write from ### Tool annotations (MCP hints) This server sets [MCP ToolAnnotations](https://modelcontextprotocol.io/specification/2025-03-26/server/tools#toolannotations) on each tool so clients can: - Distinguish **read‑only** tools from write‑capable tools. - Understand which write operations are **idempotent** (safe to retry with the same arguments). - Highlight operations that may be **destructive** (overwriting or heavily mutating data). - Signal that a tool does **not** reach an open or external world (every filesystem tool sets `openWorldHint: false`). The mapping for filesystem tools is: | Tool | readOnlyHint | idempotentHint | destructiveHint | Notes | |-----------------------------|--------------|----------------|-----------------|--------------------------------------------------| | `read_text_file` | `true` | – | – | Pure read | | `read_media_file` | `true` | – | – | Pure read | | `read_multiple_files` | `true` | – | – | Pure read | | `list_directory` | `true` | – | – | Pure read | | `list_directory_with_sizes` | `true` | – | – | Pure read | | `directory_tree` | `true` | – | – | Pure read | | `search_files` | `true` | – | – | Pure read | | `get_file_info` | `true` | – | – | Pure read | | `list_allowed_directories` | `true` | – | – | Pure read | | `create_directory` | `false` | `true` | `false` | Re‑creating the same dir is a no‑op | | `write_file` | `false` | `true` | `true` | Overwrites existing files | | `edit_file` | `false` | `false` | `true` | Re‑applying edits can fail or double‑apply | | `move_file` | `false` | `false` | `true` | Deletes source file | > Note: `idempotentHint` and `destructiveHint` are meaningful only when `readOnlyHint` is `false`, as defined by the MCP spec. Every tool also sets `openWorldHint: false` — this server only accesses the local filesystem within its allowed directories, never an open or external world. ## Usage with Claude Desktop Add this to your `claude_desktop_config.json`: Note: you can provide sandboxed directories to the server by mounting them to `/projects`. Adding the `ro` flag will make the directory readonly by the server. ### Docker Note: all directories must be mounted to `/projects` by default. ```json { "mcpServers": { "filesystem": { "command": "docker", "args": [ "run", "-i", "--rm", "--mount", "type=bind,src=/Users/username/Desktop,dst=/projects/Desktop", "--mount", "type=bind,src=/path/to/other/allowed/dir,dst=/projects/other/allowed/dir,ro", "--mount", "type=bind,src=/path/to/file.txt,dst=/projects/path/to/file.txt", "mcp/filesystem", "/projects" ] } } } ``` ### NPX ```json { "mcpServers": { "filesystem": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-filesystem", "/Users/username/Desktop", "/path/to/other/allowed/dir" ] } } } ``` On Windows, use `cmd /c` to launch `npx`: ```json { "mcpServers": { "filesystem": { "command": "cmd", "args": [ "/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "/Users/username/Desktop", "/path/to/other/allowed/dir" ] } } } ``` ## Usage with VS Code For quick installation, click the installation buttons below... [](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40modelcontextprotocol%2Fserver-filesystem%22%2C%22%24%7BworkspaceFolder%7D%22%5D%7D) [](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40modelcontextprotocol%2Fserver-filesystem%22%2C%22%24%7BworkspaceFolder%7D%22%5D%7D&quality=insiders) [](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22--mount%22%2C%22type%3Dbind%2Csrc%3D%24%7BworkspaceFolder%7D%2Cdst%3D%2Fprojects%2Fworkspace%22%2C%22mcp%2Ffilesystem%22%2C%22%2Fprojects%22%5D%7D) [](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22--mount%22%2C%22type%3Dbind%2Csrc%3D%24%7BworkspaceFolder%7D%2Cdst%3D%2Fprojects%2Fworkspace%22%2C%22mcp%2Ffilesystem%22%2C%22%2Fprojects%22%5D%7D&quality=insiders) For manual installation, you can configure the MCP server using one of these methods: **Method 1: User Configuration (Recommended)** Add the configuration to your user-level MCP configuration file. Open the Command Palette (`Ctrl + Shift + P`) and run `MCP: Open User Configuration`. This will open your user `mcp.json` file where you can add the server configuration. **Method 2: Workspace Configuration** Alternatively, you can add the configuration to a file called `.vscode/mcp.json` in your workspace. This will allow you to share the configuration with others. > For more details about MCP configuration in VS Code, see the [official VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers). You can provide sandboxed directories to the server by mounting them to `/projects`. Adding the `ro` flag will make the directory readonly by the server. ### Docker Note: all directories must be mounted to `/projects` by default. ```json { "servers": { "filesystem": { "command": "docker", "args": [ "run", "-i", "--rm", "--mount", "type=bind,src=${workspaceFolder},dst=/projects/workspace", "mcp/filesystem", "/projects" ] } } } ``` ### NPX ```json { "servers": { "filesystem": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-filesystem", "${workspaceFolder}" ] } } } ``` On Windows, use: ```json { "servers": { "filesystem": { "command": "cmd", "args": [ "/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "${workspaceFolder}" ] } } } ``` ## Build Docker build: ```bash docker build -t mcp/filesystem -f src/filesystem/Dockerfile . ``` ## License This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.