Filesystem MCP server

Install

What it lets the assistant do

• Read text and media files Read read_text_file (with optional head or tail line counts), read_media_file (base64 with a MIME type) and read_multiple_files, where one failed read does not stop the rest.
• List folders and get file details Read list_directory marks each entry [FILE] or [DIR]; list_directory_with_sizes adds sizes, totals and sorting by name or size; get_file_info returns size, created, modified and accessed times, type and permissions.
• Map a folder as JSON Read directory_tree returns a recursive JSON tree of names, types and children, formatted with two-space indentation, and accepts glob exclude patterns. On a large folder the tree is long.
• Search by pattern Read search_files matches glob patterns recursively from a starting folder, returns full paths to every match, and takes exclude patterns, so folders such as node_modules or .git can stay out of the results.
• Create or overwrite files Write write_file creates a new file or replaces an existing one. The README says to exercise caution, and the tool is annotated as destructive.
• Edit files by matching text Write edit_file replaces matched text and returns a git-style diff. dryRun previews the change without applying it, and the README calls using it first best practice.
• Create folders and move files Write create_directory creates any missing parents. move_file moves or renames, fails if the destination exists, and is annotated destructive because the source path goes away.
• List the allowed directories Read list_allowed_directories shows exactly which folders the server can touch at that moment. The server needs at least one allowed directory to run.
• Label each tool for your client Read Every tool carries MCP hints: nine are read-only, create_directory is idempotent, and write_file, edit_file and move_file are marked destructive. The MCP specification tells clients to treat such hints as untrusted unless the server is trusted.

Tools checked one by one against the repository README on 2026-10-15.

Before you connect it

1. 1Allow one project folder, not your home directory. Every operation is limited to the allowed directories, so the folders you pass are the whole reach of the server.
2. 2Know that Roots replace your list. If your client supports MCP Roots, the roots it sends completely replace the directories passed on the command line, and they can change mid-session through roots/list_changed.
3. 3Commit or back up before a session. write_file overwrites, edit_file changes files in place and move_file removes the source path, and the README documents no undo or trash. A clean git status means every change can be reverted.
4. 4Keep secrets outside the allowed folders. A .env or key file inside an allowed folder is readable by read_text_file like any other file, and what it returns goes into the assistant’s context.
5. 5Use Docker for read-only access. The README’s Docker setup runs the mcp/filesystem image with each folder mounted under /projects, which by default is the only place the container looks. Adding ro to a mount makes that folder read-only to the server, so the assistant can read a reference project without being able to change it.
6. 6Prefer Roots when your client offers them. The README recommends Roots because the allowed directories then follow the client’s workspace and update without a restart. If the server starts with no folder arguments and the client sends no roots, it stops with an error.
7. 7Preview edits first. Ask for edit_file with dryRun set to true, read the diff, then let the real edit run. Keep your client’s confirmation prompt on for write_file and move_file.
8. 8Mind binary files. read_media_file returns images and audio as content blocks and any other file type as an embedded resource, so whatever file you point it at is sent to the assistant as base64.
9. 9Check the allowed list at the start of a session. If the client has changed its roots, list_allowed_directories shows the new folders before anything is written.
10. 10Use the Windows block on Windows. The README launches npx through cmd /c there, so copy its Windows configuration rather than the macOS one.
11. 11Remember what a reference server is. The servers repository calls these reference implementations and educational examples, not production-ready solutions. If you fork it, read the LICENSE: the server README says MIT, while the repository is moving new contributions to Apache-2.0.