Filesystem

Operasi file yang aman dengan kontrol akses yang dapat dikonfigurasi

GitHub

91.9k

Dokumentasi

Filesystem MCP Server

Node.js server implementing Model Context Protocol (MCP) for filesystem operations.

Published on npm as @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 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 can also replace them at runtime, but Roots is deprecated as of protocol version 2026-07-28 and a 2026-07-28 connection cannot use it.

Method 1: Command-line Arguments (Recommended)

Specify Allowed directories when starting the server:

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:

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

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:

Server Startup
- Server starts with directories from command-line arguments (if provided)
- If no arguments provided, server starts with empty allowed directories
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)
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
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
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, 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
- 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
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 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.

{
  "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

{
  "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:

{
  "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...

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.

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.

{
  "servers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount", "type=bind,src=${workspaceFolder},dst=/projects/workspace",
        "mcp/filesystem",
        "/projects"
      ]
    }
  }
}

NPX

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${workspaceFolder}"
      ]
    }
  }
}

On Windows, use:

{
  "servers": {
    "filesystem": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${workspaceFolder}"
      ]
    }
  }
}

Build

Docker build:

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.