Skip to content

Commit b71b3da

Browse files
authored
Merge pull request #5451 from modelcontextprotocol/v2/feat/5348-filesystem-read-only-dirs
filesystem: per-directory read-only access with --read-only-dir
2 parents 7b4bdaa + b71bad9 commit b71b3da

13 files changed

Lines changed: 973 additions & 80 deletions
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@modelcontextprotocol/server-filesystem": minor
3+
---
4+
5+
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.

‎src/filesystem/README.md‎

Lines changed: 58 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -19,15 +19,21 @@ Published on npm as [`@modelcontextprotocol/server-filesystem`](https://www.npmj
1919
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.
2020

2121
### Method 1: Command-line Arguments (Recommended)
22+
2223
Specify Allowed directories when starting the server:
24+
2325
```bash
2426
mcp-server-filesystem /path/to/dir1 /path/to/dir2
2527
```
2628

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+
2731
This is the only method that works on every protocol version, so it is the one to use.
2832

2933
### Read-only Mode
34+
3035
Add `--read-only` to serve only the tools that cannot change the filesystem:
36+
3137
```bash
3238
mcp-server-filesystem --read-only /path/to/dir1 /path/to/dir2
3339
```
@@ -36,15 +42,35 @@ The server then registers only the tools annotated `readOnlyHint: true` in the [
3642

3743
The flag may appear anywhere among the arguments. `--` ends the options, so a directory literally named `--read-only` can be given after it.
3844

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:
50+
51+
```bash
52+
mcp-server-filesystem --read-only-dir /path/to/reference /path/to/workspace
53+
```
54+
55+
- 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.
4063

4164
### Method 2: MCP Roots (Deprecated, 2025-era clients only)
65+
4266
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.
4367

4468
Roots notified by Client to Server, completely replace any server-side Allowed directories when provided.
4569

4670
#### Confining Roots to the command-line directories
71+
4772
To keep a client's Roots inside the directories you gave on the command line, add `--confine-roots`:
73+
4874
```bash
4975
mcp-server-filesystem --confine-roots /path/to/dir1 /path/to/dir2
5076
```
@@ -75,7 +101,6 @@ The server's directory access control follows this flow:
75101
- The client's first message picks the protocol era of the connection
76102
- 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
77103
- A **2025-era** client sends `initialize` with its capabilities, and the server checks whether it supports roots (`capabilities.roots`)
78-
79104
3. **Roots Protocol Handling** (2025-era clients that support roots)
80105
- **On initialization**: Server requests roots from client via `roots/list`
81106
- Client responds with its configured roots
@@ -105,8 +130,6 @@ The server's directory access control follows this flow:
105130
106131
**Note**: The server will only allow operations within directories specified either via `args` or, for a 2025-era client, via Roots.
107132
108-
109-
110133
## API
111134
112135
### Resources
@@ -299,7 +322,6 @@ Files inside the allowed directories are also [resources](https://modelcontextpr
299322
entries below it do not count toward the 100,000-entry bound
300323
- Output is formatted with 2-space indentation for readability
301324
- Bounded: see [Slow and very large trees](#slow-and-very-large-trees)
302-
303325
- **get_file_info**
304326
- Get detailed file/directory metadata
305327
- Input: `path` (string)
@@ -330,11 +352,11 @@ request from stalling the server:
330352
- **Resolving a path (in any tool), and each directory read in `search_files`
331353
and `directory_tree`, waits at most 15 seconds.** A call that takes longer ends
332354
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
334356
refused, never admitted.
335357
- **`search_files` and `directory_tree` visit at most 100,000 entries.** A walk
336358
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.
338360
339361
Either error means: narrow `path`, or name the slow or large folder in
340362
`excludePatterns`. A timed-out call cannot be cancelled and finishes in the
@@ -353,23 +375,23 @@ on each tool so clients can:
353375
354376
The mapping for filesystem tools is:
355377
356-
| Tool | readOnlyHint | idempotentHint | destructiveHint | Notes |
357-
|-----------------------------|--------------|----------------|-----------------|--------------------------------------------------|
358-
| `read_file` | `true` | `true` | `false` | Deprecated alias of `read_text_file` |
359-
| `read_text_file` | `true` | `true` | `false` | Pure read |
360-
| `read_media_file` | `true` | `true` | `false` | Pure read |
361-
| `read_multiple_files` | `true` | `true` | `false` | Pure read |
362-
| `list_directory` | `true` | `true` | `false` | Pure read |
363-
| `list_directory_with_sizes` | `true` | `true` | `false` | Pure read |
364-
| `directory_tree` | `true` | `true` | `false` | Pure read |
365-
| `search_files` | `true` | `true` | `false` | Pure read |
366-
| `get_file_info` | `true` | `true` | `false` | Pure read |
367-
| `list_allowed_directories` | `true` | `true` | `false` | Pure read |
368-
| `create_directory` | `false` | `true` | `false` | Re‑creating the same dir is a no‑op |
369-
| `write_file` | `false` | `true` | `true` | Overwrites existing files |
370-
| `append_file` | `false` | `false` | `false` | Adds to a file; repeating it appends again |
371-
| `edit_file` | `false` | `false` | `true` | Re‑applying edits can fail or double‑apply |
372-
| `move_file` | `false` | `false` | `true` | Deletes source file |
378+
| Tool | readOnlyHint | idempotentHint | destructiveHint | Notes |
379+
| --------------------------- | ------------ | -------------- | --------------- | -------------------------------------------------- |
380+
| `read_file` | `true` | `true` | `false` | Deprecated alias of `read_text_file` |
381+
| `read_text_file` | `true` | `true` | `false` | Pure read |
382+
| `read_media_file` | `true` | `true` | `false` | Pure read |
383+
| `read_multiple_files` | `true` | `true` | `false` | Pure read |
384+
| `list_directory` | `true` | `true` | `false` | Pure read |
385+
| `list_directory_with_sizes` | `true` | `true` | `false` | Pure read |
386+
| `directory_tree` | `true` | `true` | `false` | Pure read |
387+
| `search_files` | `true` | `true` | `false` | Pure read |
388+
| `get_file_info` | `true` | `true` | `false` | Pure read |
389+
| `list_allowed_directories` | `true` | `true` | `false` | Pure read |
390+
| `create_directory` | `false` | `true` | `false` | Re‑creating the same dir is a no‑op |
391+
| `write_file` | `false` | `true` | `true` | Overwrites existing files |
392+
| `append_file` | `false` | `false` | `false` | Adds to a file; repeating it appends again |
393+
| `edit_file` | `false` | `false` | `true` | Re‑applying edits can fail or double‑apply |
394+
| `move_file` | `false` | `false` | `true` | Deletes source file |
373395
| `copy_file` | `false` | `true` | `false` | Never overwrites; a repeat fails, changing nothing |
374396
375397
> 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:
379401
Node.js 24 or later, when the server runs through `npx` or from source.
380402
381403
## Usage with Claude Desktop
404+
382405
Add this to your `claude_desktop_config.json`:
383406
384407
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.
385408
386409
### Docker
410+
387411
Note: all directories must be mounted to `/projects` by default.
388412
389413
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
397421
"run",
398422
"-i",
399423
"--rm",
400-
"--mount", "type=bind,src=/Users/username/Desktop,dst=/projects/Desktop",
401-
"--mount", "type=bind,src=/path/to/other/allowed/dir,dst=/projects/other/allowed/dir,ro",
402-
"--mount", "type=bind,src=/path/to/file.txt,dst=/projects/path/to/file.txt",
424+
"--mount",
425+
"type=bind,src=/Users/username/Desktop,dst=/projects/Desktop",
426+
"--mount",
427+
"type=bind,src=/path/to/other/allowed/dir,dst=/projects/other/allowed/dir,ro",
428+
"--mount",
429+
"type=bind,src=/path/to/file.txt,dst=/projects/path/to/file.txt",
403430
"mcp/filesystem",
404431
"/projects"
405432
]
@@ -467,7 +494,8 @@ Alternatively, you can add the configuration to a file called `.vscode/mcp.json`
467494
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.
468495

469496
### Docker
470-
Note: all directories must be mounted to `/projects` by default.
497+
498+
Note: all directories must be mounted to `/projects` by default.
471499

472500
```json
473501
{
@@ -478,7 +506,8 @@ Note: all directories must be mounted to `/projects` by default.
478506
"run",
479507
"-i",
480508
"--rm",
481-
"--mount", "type=bind,src=${workspaceFolder},dst=/projects/workspace",
509+
"--mount",
510+
"type=bind,src=${workspaceFolder},dst=/projects/workspace",
482511
"mcp/filesystem",
483512
"/projects"
484513
]

‎src/filesystem/__tests__/confine-roots.test.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -227,11 +227,13 @@ describe("the command line", () => {
227227
directories: ["/a"],
228228
readOnly: false,
229229
confineRoots: true,
230+
readOnlyDirectories: [],
230231
});
231232
expect(parseArgs(["--", "--confine-roots"])).toEqual({
232233
directories: ["--confine-roots"],
233234
readOnly: false,
234235
confineRoots: false,
236+
readOnlyDirectories: [],
235237
});
236238
});
237239

0 commit comments

Comments
 (0)