# 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
```

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, run two servers: one with `--read-only` for the directories to protect, and one without it for the rest. That separation holds only while the writable server keeps its command-line directories: a 2025-era client that supports Roots replaces them (see Method 2), so it could expose a protected directory to the writable server, unless that server is started with `--confine-roots` (see below). Where that matters, 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

**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

- **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
  - 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
  - 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 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
  - 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[]): Exclude any patterns. 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[]): Exclude any patterns. Glob formats are supported.
    - `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.

```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.