Filesystem MCP

Official MCP reference server for controlled local file operations within allowed directories.

Description

What Filesystem MCP is for

Filesystem MCP is an official Model Context Protocol reference server for local file operations. It is maintained in the modelcontextprotocol/servers repository, and the npm package is published as @modelcontextprotocol/server-filesystem. Its value is not a flashy niche feature; it provides one of the most important foundations for practical AI agents: controlled access to files and directories. An agent can read project files, compare multiple files, create new files, apply targeted edits, inspect directory trees, and retrieve metadata without the user manually pasting every relevant file into the chat.

Capabilities and practical use cases

According to the official README, the server supports tools including read_text_file, read_media_file, read_multiple_files, write_file, edit_file, create_directory, list_directory, directory_tree, move_file, search_files, get_file_info, and list_allowed_directories. That toolset makes Filesystem MCP useful for coding agents, technical writing, documentation maintenance, and local knowledge bases. In a software project, an assistant can inspect configuration files, update documentation, find tests, or prepare small refactors. In an editorial workflow, the same server can make local Markdown or text collections available for structured review.

The strength of the server is also its main responsibility: it operates on the local filesystem. That makes it much more powerful than a simple search tool, but also riskier. Write-oriented tools can create, overwrite, move, or modify files. For real work, this is valuable because an agent can prepare actual changes instead of only suggesting them. For experiments or directories containing sensitive information, broad access would be the wrong default.

Directory access control and Roots

Filesystem MCP restricts access to allowed directories. According to the documentation, those directories can be passed as command-line arguments at startup or supplied dynamically by the client through the MCP Roots protocol. When the client supports Roots, it can provide allowed directories during initialization and later update them through roots/list_changed notifications. Roots supplied by the client fully replace server-side directories. If the server starts without command-line arguments and the client does not provide Roots, initialization fails according to the README.

That detail matters in practice. Do not expose the whole home directory, the whole disk, or folders containing SSH keys, browser profiles, production configuration, or credentials. Narrow project folders are the safer pattern, ideally under version control. Docker deployments can add another guardrail by mounting directories read-only when write access is not required. The list_allowed_directories tool helps the user or host inspect which paths are currently available.

Installation and operation

The typical start command in the documentation uses npx, for example npx -y @modelcontextprotocol/server-filesystem /path/to/project. Docker is also supported. In MCP clients, the server is registered as a stdio server; allowed paths are either listed in args or supplied through Roots. The server itself does not require an account with an external service and does not introduce a vendor subscription. The relevant permission boundary is the local operating-system account: what that account can read or write inside the allowed directory can generally be reached through the MCP tool.

Who benefits most from Filesystem MCP?

Filesystem MCP is useful for users who want AI agents to work with local files while still placing a clear boundary around where they may operate. Common questions are important: Is it free? Yes, according to the project it is open source; only your own runtime environment may cost money. Is it safe? Only with narrow Roots, backups, and a review workflow. Can it damage files? Yes, write and move tools can make real changes. The best setup is a clearly scoped working directory where agent assistance is welcome and every change can be reviewed through version control.

Requirements

An MCP client plus Node.js with npx, or Docker as an alternative. At least one allowed directory must be passed at startup unless the client supplies MCP Roots.

Installation instructions

Filesystem MCP gives an AI client direct access to local files. The important question is therefore not only whether the server starts, but which directories and write permissions it receives.

Requirements for Filesystem MCP

You need an MCP client and Node.js with npx. The official Docker image is an alternative. Choose the smallest practical project folder in advance; do not expose your home directory, SSH keys, password stores, or global configuration folders.

Step 1: Setting up Filesystem MCP with npx

bash
npx -y @modelcontextprotocol/server-filesystem /absolute/path/to/project

Add the command and path to your client's MCP configuration. Every additional path increases the attack and error surface. If the client supports MCP Roots, it can supply allowed directories dynamically; these roots replace startup arguments.

Limiting Filesystem MCP write access

The server includes tools that can overwrite, edit, and move files. For analysis-only work, a read-only Docker mount marked ro is the safest option. When write access is enabled, keep files under version control or backed up and review changes before committing them.

Step 2: Verifying the setup

After startup, use list_allowed_directories to verify the effective directory allowlist. Also use a harmless test file to confirm that reading and, if intended, writing work as expected.

Common setup mistakes

A frequently overlooked problem is using a relative instead of an absolute path at startup — some clients resolve relative paths against a different working directory than expected, causing the server to expose the wrong directory or fail to start at all. Another pitfall is accidentally exposing a parent folder instead of the actual project folder, for example when the entire home directory is specified for convenience instead of a subfolder. It's therefore always worth double-checking the actual path passed before going into production use.

Combining with other MCP servers

Filesystem MCP combines well with research tools like Fetch MCP: one server retrieves information from the web, the other stores it in a structured way in the project folder or reconciles it with existing files. This combination calls for extra caution when unreviewed web content flows into write operations — an agent should never blindly translate instructions from a fetched web page into file changes.

For teams with multiple projects

Anyone wanting to use Filesystem MCP for several projects at once should set up a separate server instance with its own exposed path for each project, rather than sharing a common parent directory. This prevents an agent from accidentally modifying files in the wrong project when multiple tasks run in parallel.

Backing up before the first write access

Before write tools are used in production for the first time, a full backup of the exposed folder is worth doing, for example via a git commit or a simple copy. That way, any unexpected change can be undone without depending on working version control inside the project itself.

Source: official modelcontextprotocol/servers repository, checked on 2026-09-03.

npx -y @modelcontextprotocol/server-filesystem /pfad/zum/verzeichnis

Authentication

No separate login. The server runs locally over stdio. Access is governed by the operating-system account and the directories allowed at startup or through MCP Roots.

Required access permissions

Read and, by default, write permissions of the executing account inside the allowed directories. Tools can read, create, overwrite, edit, and move files and create directories. Read-only Docker mounts can restrict access to reading.

Transmitted or stored data

File contents, names, paths, directory trees, and metadata from allowed directories are sent to the MCP client and potentially to its language model. Write operations modify or store data directly in the local filesystem. The server itself does not send files to an external service of its own.

Security risks

Overly broad roots can expose confidential files. Write tools can overwrite, move, or create content; the official tool annotations explicitly classify several operations as potentially destructive. Allow narrowly scoped project folders, exclude sensitive paths, enable write access only when needed, and version or back up changes.

License and costs

License
Apache-2.0 / MIT (transitional)
Cost
free

The reference server is open-source and free. Only your own runtime environment may incur costs.

Alternatives

At a glance

Status
Official server
Deployment
Local
Current version
2026.8.31
GitHub stars
91,877
Last reviewed
06.09.2026

Repository and documentation

Categories

Supported clients

Related guides

Guides and background related to this entry.

No related guides yet.