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 b766bc2
Browse filesBrowse the repository at this point in the historyBrowse files
feat(filesystem): per-directory read-only access with --read-only-dir
Add a repeatable --read-only-dir <path> option that makes one allowed
directory read-only while the others stay writable (#5348). validatePath
now takes a required access mode; a "write" validation must be handed the
read-only directories and refuses a resolved path inside any of them, so a
write tool cannot skip the check. Every write tool stays listed. move_file
checks both ends, copy_file its destination. Roots never lift the marking.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: cliffhall <[email protected]>
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, `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. `list_allowed_directories` names the read-only directories.
Copy file name to clipboardExpand all lines: src/filesystem/README.md
+18-1Lines changed: 18 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -24,6 +24,8 @@ Specify Allowed directories when starting the server:
24
24
mcp-server-filesystem /path/to/dir1 /path/to/dir2
25
25
```
26
26
27
+
Options may come before, between or after the directories: `--read-only`, `--read-only-dir <path>` (both below) and `--confine-roots` (under Method 2).
28
+
27
29
This is the only method that works on every protocol version, so it is the one to use.
28
30
29
31
### Read-only Mode
@@ -36,7 +38,22 @@ The server then registers only the tools annotated `readOnlyHint: true` in the [
36
38
37
39
The flag may appear anywhere among the arguments. `--` ends the options, so a directory literally named `--read-only` can be given after it.
38
40
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.
41
+
Read-only mode covers every allowed directory. To make only some of them read-only, use `--read-only-dir` below.
42
+
43
+
#### Read-only directories
44
+
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.
50
+
- 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; `copy_file` may copy out of one, never into it. `edit_file` is refused there even with `dryRun`.
51
+
- 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.
52
+
- 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.
53
+
- 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`.
54
+
-`list_allowed_directories` lists the read-only directories after the allowed ones, and the server logs them to stderr at startup.
55
+
56
+
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.
0 commit comments