# 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 - Directory access control from command-line arguments, with [Roots](https://modelcontextprotocol.io/docs/learn/client-concepts#roots) as a deprecated, 2025-era convenience - Serves both protocol eras on stdio: 2026-07-28 clients (`server/discover`, no handshake) and 2025-era clients (`initialize`) ## Directory Access Control The server may touch only its **allowed directories**. Pass them on the command line. A 2025-era client that supports [Roots](https://modelcontextprotocol.io/docs/learn/client-concepts#roots) can also replace them at runtime, but Roots is [deprecated as of protocol version 2026-07-28](https://modelcontextprotocol.io/specification/2026-07-28/deprecated) and a 2026-07-28 connection cannot use it. ### Method 1: Command-line Arguments (Recommended) Specify Allowed directories when starting the server: ```bash mcp-server-filesystem /path/to/dir1 /path/to/dir2 ``` Options may come before, between or after the directories: `--read-only`, `--read-only-dir ` (both below) and `--confine-roots` (under Method 2). This is the only method that works on every protocol version, so it is the one to use. ### Read-only Mode Add `--read-only` to serve only the tools that cannot change the filesystem: ```bash mcp-server-filesystem --read-only /path/to/dir1 /path/to/dir2 ``` The server then registers only the tools annotated `readOnlyHint: true` in the [Tool annotations](#tool-annotations-mcp-hints) table, the ones that read and list. Every tool not annotated `readOnlyHint: true`, that is every tool that writes (such as `write_file` and `edit_file`), is left out, so a client never lists it and a call to it fails as an unknown tool. A tool added later follows the same rule through its annotation. The server enforces this, whatever the client is configured to allow, and it works the same with `npx` as with Docker. It applies on both protocol eras, and to directories that come from a client's Roots. The flag may appear anywhere among the arguments. `--` ends the options, so a directory literally named `--read-only` can be given after it. Read-only mode covers every allowed directory. To make only some of them read-only, use `--read-only-dir` below. #### Read-only directories Add `--read-only-dir ` to make one directory read-only while the others stay writable. Repeat it for each directory to protect: ```bash mcp-server-filesystem --read-only-dir /path/to/reference /path/to/workspace ``` - A read-only directory is an allowed directory too, so it need not also be listed on its own. - Every write tool (`write_file`, `append_file`, `edit_file`, `create_directory`, `move_file` and `copy_file`) stays listed, since the other directories are writable, but refuses a target inside a read-only directory with an error such as `Access denied - read-only directory: /path/to/reference/notes.md is in /path/to/reference, which the server was started with --read-only-dir`. `move_file` is refused when either its source or its destination is inside one or contains one, so a protected directory cannot be carried away by moving its parent; `copy_file` may copy out of one, never into it. `edit_file` is refused there even with `dryRun`. - The check runs on a path's resolved location, so a symlink in a writable directory cannot route a write into a read-only one. A read-only directory must therefore exist when the server starts: one that cannot be resolved (missing, not a directory, or a dangling symlink) stops the server from starting, rather than leaving a path it could not pin down writable. - A path inside any read-only directory is refused, so a directory nested inside a read-only one is read-only too, even if it is also given as a writable directory. - The marking is fixed at startup and holds on both protocol eras. A 2025-era client's Roots can replace the allowed directories (see Method 2), but Roots say nothing about writing, so they never lift it: a write into a read-only directory is refused whichever directories are in force, with or without `--confine-roots`. - `list_allowed_directories` lists the read-only directories after the allowed ones, and the server logs them to stderr at startup. The option may appear anywhere among the arguments, and takes the next argument as its directory, whatever it is. `--` ends the options, so after it `--read-only-dir` is a directory name. With `--read-only` as well, every write tool is withheld anyway. For defence in depth, make the protected directories read-only at the operating-system level as well, with file permissions or, with Docker, a bind mount's `ro` flag. ### Method 2: MCP Roots (Deprecated, 2025-era clients only) A client that connects with a 2025-era protocol version (the `initialize` handshake) and supports [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. #### Confining Roots to the command-line directories To keep a client's Roots inside the directories you gave on the command line, add `--confine-roots`: ```bash mcp-server-filesystem --confine-roots /path/to/dir1 /path/to/dir2 ``` The client's Roots can then narrow the command-line directories but never replace or widen them. The server allows the overlap of the two: - A root inside a command-line directory is allowed as given, so a client can narrow access to one project. - A root that contains a command-line directory (for example `/`) is narrowed to that directory. - A root outside every command-line directory is ignored and logged. If every root is ignored, the server treats the update as one with no valid roots: before any root has been in force the command-line directories stay; once one has, access is revoked until the client exposes a root inside them again. This suits an operator who decides what may be shared (the command line) while letting a client say what it wants to work on (its Roots), and it keeps a client from discarding the command-line directories by advertising its working directory. Without command-line directories the flag has no effect, and the server warns at startup. Without the flag, Roots replace the command-line directories as described above. A Root reached through a symlink is allowed in both its advertised form and its resolved form, as a command-line directory is: a Root of `file:///tmp/project` on macOS allows `/tmp/project` and `/private/tmp/project`. Every requested path is still resolved and checked against the resolved directories, so a symlink inside a Root that points outside it is refused. **Important**: If server starts without command-line arguments AND a 2025-era client doesn't support roots protocol, the server fails at initialization: it logs the reason to stderr, closes the connection and exits with status 1. A client that supports roots but provides none (or none that are valid) keeps the connection, with no allowed directories until it sends `roots/list_changed` with valid roots. The 2026-07-28 protocol has no `initialize` handshake and no server-to-client `roots/list` request, so a 2026-07-28 client's roots are never asked for: the command-line directories are the whole allow-list. A server started with none answers every tool call on such a connection with an error saying so. ### 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** - The client's first message picks the protocol era of the connection - A **2026-07-28** client sends `server/discover` (or any request carrying the per-request `_meta` envelope): the server uses the command-line directories, and steps 3 and 4 do not apply - A **2025-era** client sends `initialize` with its capabilities, and the server checks whether it supports roots (`capabilities.roots`) 3. **Roots Protocol Handling** (2025-era clients that support 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 (with `--confine-roots`, with their overlap with the command-line directories) - Tool calls that arrive before the initial roots are loaded wait for them, so they are checked against the client's roots - **On runtime updates**: Client can send `notifications/roots/list_changed` - Server requests updated roots and replaces allowed directories again - Tool calls that arrive while an update is being fetched wait for it, so none runs against a root the client has just withdrawn - Once the client's roots are in force, an update with no valid roots revokes access: every path is refused ("Access denied - no allowed directories") until the client exposes a root again. Before any root has been in force, such an update keeps the command-line directories 4. **Fallback Behavior** (2025-era clients that don't support roots) - Server continues using command-line directories only - No dynamic updates possible - With no command-line directories either, the server logs an error, closes the connection and exits with status 1 5. **Access Control** - All filesystem operations are restricted to allowed directories - Use `list_allowed_directories` tool to see current directories - The server also logs the effective allowed directories to stderr, with where they came from (the command line, or the client's Roots and whether those replaced the command-line directories), at startup and whenever they change: after `initialize`, after each Roots update, and when a withdrawal leaves none. For example: ``` Effective allowed directories (from the client's Roots, which replaced the command-line directories): /Users/username/project ``` - Server requires at least ONE allowed directory to operate - On Windows, a path naming an NTFS alternate data stream (`file.txt:stream`, `file.txt::$DATA`) is refused with "Access denied - NTFS alternate data stream paths are not supported", even inside an allowed directory: a colon is accepted only as a drive letter's (`C:\`, `\\?\C:\`). A stream holds data that no directory listing or diff of the file shows. On macOS and Linux a colon is an ordinary file-name character and is not refused - On Windows, a path any of whose components is a reserved device name (`CON`, `PRN`, `AUX`, `NUL`, `COM1`-`COM9`, `LPT1`-`LPT9`, in any case and with or without an extension, such as `NUL.txt`) is refused with "Access denied - Windows reserved device names ... are not supported", and one any of whose components ends in a dot or a space (`file.txt.`, `dir \file.txt`) with "Access denied - Windows path components ending in a dot or a space are not supported". Windows opens the device rather than a file in the directory, and strips trailing dots and spaces so the name refers to a different file. `.` and `..` are not affected. On macOS and Linux these are ordinary file names and are not refused **Note**: The server will only allow operations within directories specified either via `args` or, for a 2025-era client, via Roots. ## API ### Resources Files inside the allowed directories are also [resources](https://modelcontextprotocol.io/specification/2026-07-28/server/resources), so a client application can read one with `resources/read` and decide itself what to do with it (attach it to the model's context, show it to the user), rather than relaying it through a tool result. - **Resource template** `file://{+path}` (name `file`) - Read any file by its absolute `file://` URI, for example `file:///home/user/project/README.md`. A path with spaces or other reserved characters is percent-encoded, as in any `file://` URL. - Text files are returned as `text`, with a MIME type from the extension (`text/plain` for an unknown extension whose bytes are UTF-8). Images, audio, PDFs and other binary files are returned as a base64 `blob` with their MIME type (`application/octet-stream` when unknown). - Confined exactly as the tools are: a URI outside the allowed directories, or a symlink whose target is outside them, is refused with an `Access denied` error (`-32602`). A missing file is "resource not found" (`-32602` with the URI in the error data), and a directory is not a resource. - `resources/list` returns nothing: the server never enumerates the disk. Find files with `list_directory`, `directory_tree` or `search_files`, then read them by URI. - Results carry a cache hint of `ttlMs: 0`, `cacheScope: "private"` (2026-07-28), since a file can change at any time. ### Tools - **read_text_file** - Read complete contents of a file as text - Inputs: - `path` (string) - `head` (non-negative integer, optional): First N lines; `0` returns no lines - `tail` (non-negative integer, optional): Last N lines; `0` returns no lines - Always treats the file as UTF-8 text regardless of extension - Cannot specify both `head` and `tail` simultaneously - Reads only a regular file: a FIFO, socket or device is refused rather than read, as it is by every tool and by `resources/read` - **read_media_file** - Read a file and return it as a base64-encoded content block with its MIME type - Inputs: - `path` (string) - Reads 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 - Does not create directories: when the file's directory does not exist, it fails with `Parent directory does not exist: `; create the directory first with `create_directory`. `append_file`, `move_file` and `copy_file` fail the same way for a missing destination directory - An existing file is overwritten in place, so it keeps its inode, creation time, hard links and permissions (`edit_file` writes the same way). The overwrite is not crash-atomic: a crash mid-write can leave the file partly written. A read-only file is refused rather than replaced - Allowed-directory checks are path-based: they check the name you pass, not every name the file has. A hard link is a real name of the same file, so when a file inside an allowed directory is also hard-linked from somewhere else (pnpm, for example, hard-links package files into `node_modules` from its store), overwriting or editing it changes the content at every name, inside the allowed directories or not. `get_file_info` reports a file's `hardLinks` count; more than 1 means the file has other names - **append_file** - Append text to the end of a file, creating the file if it does not exist - Inputs: - `path` (string): File location - `content` (string): Text to append - The text is appended exactly as given: no newline is added before or after it. To build a file line by line, end each `content` with `\n` - The existing content is never changed. The file is appended to in place, so it keeps its inode, creation time, hard links and permissions, and a path that is not a regular file (a directory, say) is refused. The same hard-link caveat as `write_file` applies - **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: when only whitespace differs, each replacement line takes the indentation of the line it replaces - Preserves the file's line endings (LF or CRLF) - 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 - Matching: `oldText` must match the file's text exactly, except that line endings never matter and, when there is no exact match, a run of whole lines matches if each line is equal once leading and trailing whitespace is ignored. Whitespace inside a line must match; nothing fuzzier is tried. A newline at the end of `oldText` ends its last line rather than adding an empty one, so whole lines copied with their final newline still match when only indentation differs; the matched lines must then be followed by a newline in the file, and that newline is kept only if `newText` also ends with one - If any edit has no match, no edits are applied, and the error names the edit, quotes the closest lines of the file with line numbers, and shows the first line that differs (JSON-quoted, so tabs and trailing spaces are visible) - 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 the entries directly inside a directory, one per line, with [FILE] or [DIR] prefixes - Input: `path` (string) - For sizes or a size-sorted listing, use `list_directory_with_sizes`; for a recursive view, use `directory_tree` - **list_directory_with_sizes** - List the entries directly inside a directory with [FILE] or [DIR] prefixes, including file sizes - Use it when sizes matter (finding the largest files, say); for names only, use `list_directory`, which returns less text - Inputs: - `path` (string): Directory path to list - `sortBy` (string, optional): Sort entries by "name" or "size" (default: "name"; "size" lists the largest first) - Returns detailed listing with file sizes and summary statistics - Shows total files, directories, and combined size - An entry that cannot be stat'd (unreadable, a dangling symlink, or a symlink leaving the allowed directories) is listed with size `unknown` and left out of the combined size - **move_file** - Move or rename files and directories - Inputs: - `source` (string) - `destination` (string) - Fails if destination exists - Across filesystems (the source and destination on different mounts or disks), a regular file is moved by copying it to a newly created destination, with its permissions and modification time, and then removing the source. If the copy fails, the partial destination is removed and the source is left in place. A directory cannot be moved across filesystems and fails with an error; move its files one at a time instead - **copy_file** - Copy a file to a new location, without its content passing through the conversation - Inputs: - `source` (string): The file to copy - `destination` (string): Where to create the copy - Fails if destination exists: it never overwrites - Copies one regular file, with its permissions and modification time, into a newly created destination. A directory, or anything else that is not a regular file, is refused; create the directory and copy its files one at a time instead. If the copy fails, the partial destination is removed. The source is never changed - **search_files** - Recursively find files/directories by name (a glob over their paths), not by content: it never reads or searches inside files - Inputs: - `path` (string): Starting directory - `pattern` (string): Glob matched, case-sensitively, against each entry's path relative to `path`: `*.ext` matches entries directly under `path`, `**/*.ext` or `**/name` matches at any depth - `excludePatterns` (string[]): Entries to leave out, read the same way as `directory_tree`'s. A bare name such as `node_modules` excludes an entry of that name at any depth and everything below it; it matches whole names, so `node_modules_old` is kept. A pattern containing `*` is a glob matched against the path relative to `path` as written: `*.log` excludes only entries directly under `path`, `**/*.log` at any depth. A glob ending in `/**` also excludes the directory it names, so `**/node_modules/**` leaves out every `node_modules` directory itself, not only what is inside it. An excluded entry is skipped before it is resolved or read, so excluding a slow folder keeps the search out of it entirely. - Glob-style pattern matching - Returns full paths to matches - Bounded: see [Slow and very large trees](#slow-and-very-large-trees) - A subdirectory that cannot be read (no permission, say) is skipped, and the result says so: after the matches, a note that the search is incomplete lists each unreadable directory with its error code. Paths outside the allowed directories are still skipped silently. - **directory_tree** - Get recursive JSON tree structure of directory contents - Inputs: - `path` (string): Starting directory - `excludePatterns` (string[]): Entries to leave out, read the same way as `search_files`'s: a bare name excludes that name at any depth and the subtree below it, and a pattern containing `*` is a glob matched against the path relative to `path` as written. A glob ending in `/**` also excludes the directory it names, so it is not listed, even as empty, and is never read. - `depth` (positive integer, optional): How many levels to descend. `1` lists only the entries directly in `path`, `2` adds their children, and so on. Omitted, the whole tree is returned - 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 - Omitted for directories at the last level when `depth` is set: they are not read, so whether they hold anything is not reported - A `depth` limit also keeps the walk out of deeper levels entirely, so entries below it do not count toward the 100,000-entry bound - Output is formatted with 2-space indentation for readability - Bounded: see [Slow and very large trees](#slow-and-very-large-trees) - **get_file_info** - Get detailed file/directory metadata - Input: `path` (string) - Returns: - Size - Creation time - Modified time - Access time - Type (file/directory) - Permissions - Hard-link count (`hardLinks`): the number of names the file has. More than 1 means a write through this name changes the file at its other names too (see `write_file`) - **list_allowed_directories** - List all directories the server is allowed to access - No input required - Returns: - Directories that this server can read/write from. A directory reached through a symlink is listed twice, in the form it was given and in its resolved form ### Slow and very large trees A folder backed by a cloud-storage provider (macOS `~/Library/CloudStorage`, iCloud Drive) or a slow network mount can make a single filesystem call block for minutes while the provider fetches metadata. Two fixed limits keep one request from stalling the server: - **Resolving a path (in any tool), and each directory read in `search_files` and `directory_tree`, waits at most 15 seconds.** A call that takes longer ends the request with an error naming the path (`Filesystem call timed out after 15000 ms: ...`). A path whose real location cannot be read in time is refused, never admitted. - **`search_files` and `directory_tree` visit at most 100,000 entries.** A walk that reaches the cap ends with an error (`... stopped after visiting 100000 entries ...`) rather than a partial result. Excluded entries do not count. Either error means: narrow `path`, or name the slow or large folder in `excludePatterns`. A timed-out call cannot be cancelled and finishes in the background, so a provider that stalls repeatedly can still slow the server's other file operations until it answers. ### 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_file` | `true` | `true` | `false` | Deprecated alias of `read_text_file` | | `read_text_file` | `true` | `true` | `false` | Pure read | | `read_media_file` | `true` | `true` | `false` | Pure read | | `read_multiple_files` | `true` | `true` | `false` | Pure read | | `list_directory` | `true` | `true` | `false` | Pure read | | `list_directory_with_sizes` | `true` | `true` | `false` | Pure read | | `directory_tree` | `true` | `true` | `false` | Pure read | | `search_files` | `true` | `true` | `false` | Pure read | | `get_file_info` | `true` | `true` | `false` | Pure read | | `list_allowed_directories` | `true` | `true` | `false` | Pure read | | `create_directory` | `false` | `true` | `false` | Re‑creating the same dir is a no‑op | | `write_file` | `false` | `true` | `true` | Overwrites existing files | | `append_file` | `false` | `false` | `false` | Adds to a file; repeating it appends again | | `edit_file` | `false` | `false` | `true` | Re‑applying edits can fail or double‑apply | | `move_file` | `false` | `false` | `true` | Deletes source file | | `copy_file` | `false` | `true` | `false` | Never overwrites; a repeat fails, changing nothing | > Note: the MCP spec gives `idempotentHint` and `destructiveHint` meaning only when `readOnlyHint` is `false`, but every tool sets them anyway, so a client that reads them without checking `readOnlyHint` first still sees the truth: a read can be repeated safely and changes nothing. Every tool also sets `openWorldHint: false` — this server only accesses the local filesystem within its allowed directories, never an open or external world. ## Requirements Node.js 24 or later, when the server runs through `npx` or from source. ## 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. Note: the image runs as the unprivileged `node` user (UID 1000), not root. On a Linux host, where a bind mount keeps the host's file ownership, the server can write only where UID 1000 may, and files it creates are owned by UID 1000. If your own UID differs, add `"--user", ":"` (your `id -u` and `id -g`) before `mcp/filesystem` so it reads and writes as you. Docker Desktop on macOS and Windows maps ownership to your user and needs neither. ```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... [![Install with NPX in VS Code](https://img.shields.io/badge/VS_Code-NPM-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](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) [![Install with NPX in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-NPM-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](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) [![Install with Docker in VS Code](https://img.shields.io/badge/VS_Code-Docker-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](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) [![Install with Docker in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Docker-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](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.