You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit b71b3da
Browse filesBrowse the repository at this point in the historyBrowse files
Add `--read-only-dir <path>`, repeatable, to make one allowed directory read-only while the others stay writable. Every write tool stays listed but refuses a target inside a read-only directory (`move_file` on either end, including moving a directory that contains one, and `copy_file` on its destination), checked on the resolved path so a symlink cannot route around it; a 2025-era client's Roots never lift the marking. Each read-only directory must exist when the server starts, or it refuses to start. `list_allowed_directories` names the read-only directories.
Copy file name to clipboardExpand all lines: src/filesystem/README.md
+58-29Lines changed: 58 additions & 29 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -19,15 +19,21 @@ Published on npm as [`@modelcontextprotocol/server-filesystem`](https://www.npmj
19
19
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.
Specify Allowed directories when starting the server:
24
+
23
25
```bash
24
26
mcp-server-filesystem /path/to/dir1 /path/to/dir2
25
27
```
26
28
29
+
Options may come before, between or after the directories: `--read-only`, `--read-only-dir <path>` (both below) and `--confine-roots` (under Method 2).
30
+
27
31
This is the only method that works on every protocol version, so it is the one to use.
28
32
29
33
### Read-only Mode
34
+
30
35
Add `--read-only` to serve only the tools that cannot change the filesystem:
@@ -36,15 +42,35 @@ The server then registers only the tools annotated `readOnlyHint: true` in the [
36
42
37
43
The flag may appear anywhere among the arguments. `--` ends the options, so a directory literally named `--read-only` can be given after it.
38
44
39
-
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.
45
+
Read-only mode covers every allowed directory. To make only some of them read-only, use `--read-only-dir` below.
46
+
47
+
#### Read-only directories
48
+
49
+
Add `--read-only-dir <path>` to make one directory read-only while the others stay writable. Repeat it for each directory to protect:
- A read-only directory is an allowed directory too, so it need not also be listed on its own.
56
+
- 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`.
57
+
- 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.
58
+
- 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.
59
+
- 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`.
60
+
-`list_allowed_directories` lists the read-only directories after the allowed ones, and the server logs them to stderr at startup.
61
+
62
+
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.
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.
43
67
44
68
Roots notified by Client to Server, completely replace any server-side Allowed directories when provided.
45
69
46
70
#### Confining Roots to the command-line directories
71
+
47
72
To keep a client's Roots inside the directories you gave on the command line, add `--confine-roots`:
@@ -75,7 +101,6 @@ The server's directory access control follows this flow:
75
101
- The client's first message picks the protocol era of the connection
76
102
- 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
77
103
- A **2025-era** client sends `initialize` with its capabilities, and the server checks whether it supports roots (`capabilities.roots`)
78
-
79
104
3.**Roots Protocol Handling** (2025-era clients that support roots)
80
105
-**On initialization**: Server requests roots from client via `roots/list`
81
106
- Client responds with its configured roots
@@ -105,8 +130,6 @@ The server's directory access control follows this flow:
105
130
106
131
**Note**: The server will only allow operations within directories specified either via `args` or, for a 2025-era client, via Roots.
107
132
108
-
109
-
110
133
## API
111
134
112
135
### Resources
@@ -299,7 +322,6 @@ Files inside the allowed directories are also [resources](https://modelcontextpr
299
322
entries below it do not count toward the 100,000-entry bound
300
323
- Output is formatted with 2-space indentation for readability
301
324
- Bounded: see [Slow and very large trees](#slow-and-very-large-trees)
302
-
303
325
- **get_file_info**
304
326
- Get detailed file/directory metadata
305
327
- Input: `path` (string)
@@ -330,11 +352,11 @@ request from stalling the server:
330
352
- **Resolving a path (in any tool), and each directory read in `search_files`
331
353
and `directory_tree`, waits at most 15 seconds.** A call that takes longer ends
332
354
the request with an error naming the path (`Filesystem call timed out after
333
-
15000 ms: ...`). A path whose real location cannot be read in time is
355
+
15000 ms: ...`). A path whose real location cannot be read in time is
334
356
refused, never admitted.
335
357
- **`search_files` and `directory_tree` visit at most 100,000 entries.** A walk
336
358
that reaches the cap ends with an error (`... stopped after visiting 100000
337
-
entries ...`) rather than a partial result. Excluded entries do not count.
359
+
entries ...`) rather than a partial result. Excluded entries do not count.
338
360
339
361
Either error means: narrow `path`, or name the slow or large folder in
340
362
`excludePatterns`. A timed-out call cannot be cancelled and finishes in the
@@ -353,23 +375,23 @@ on each tool so clients can:
| `copy_file` | `false` | `true` | `false` | Never overwrites; a repeat fails, changing nothing |
374
396
375
397
> 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.
@@ -379,11 +401,13 @@ The mapping for filesystem tools is:
379
401
Node.js 24 or later, when the server runs through `npx` or from source.
380
402
381
403
## Usage with Claude Desktop
404
+
382
405
Add this to your `claude_desktop_config.json`:
383
406
384
407
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.
385
408
386
409
### Docker
410
+
387
411
Note: all directories must be mounted to `/projects` by default.
388
412
389
413
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", "<uid>:<gid>"` (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.
@@ -397,9 +421,12 @@ Note: the image runs as the unprivileged `node` user (UID 1000), not root. On a
@@ -467,7 +494,8 @@ Alternatively, you can add the configuration to a file called `.vscode/mcp.json`
467
494
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.
468
495
469
496
### Docker
470
-
Note: all directories must be mounted to `/projects` by default.
497
+
498
+
Note: all directories must be mounted to `/projects` by default.
471
499
472
500
```json
473
501
{
@@ -478,7 +506,8 @@ Note: all directories must be mounted to `/projects` by default.
0 commit comments