Filesystem MCP Server

Reference MCP server for local filesystem operations: read, write, edit, search, and inspect files within explicitly allowed directories.

Developer Tools by Anthropic / Model Context Protocol None active

GitHub Docs npm: @modelcontextprotocol/server-filesystem

Overview

The Filesystem MCP server is one of the official reference implementations maintained in the modelcontextprotocol/servers repository. It exposes secure, sandboxed filesystem access to MCP clients (Claude Desktop, Cursor, VS Code, etc.) so that an LLM can read, write, edit, search, and move files on the local machine. Access is strictly limited to directories explicitly allowed at startup or dynamically via the MCP Roots protocol, preventing the model from touching anything outside the configured paths.

The server ships 15 tools covering read operations (text, media, multiple files, directory listings, recursive tree, glob search, metadata) and write operations (write, edit with pattern matching and dry-run preview, create directory, move/rename). It also annotates tools with readOnlyHint, idempotent, and destructive hints so clients can warn users or require confirmation before destructive actions.

Distributed as the npm package @modelcontextprotocol/server-filesystem and as a Docker image, it is the canonical way to give an AI agent local file access. Because it is part of the reference servers repo, it is widely supported across MCP clients and frequently used as a starting template for building custom MCP servers.

Tools

Tool	Description
`read_text_file`	Read a text file as UTF-8, optionally limited to the first N lines (head) or last N lines (tail).
`read_media_file`	Read an image or audio file and return it as base64 with the detected MIME type.
`read_multiple_files`	Read several files at once, tolerating partial failures so one bad file does not abort the batch.
`write_file`	Create a new file or overwrite an existing one. Destructive: replaces contents without confirmation.
`edit_file`	Apply selective edits using pattern matching with whitespace normalization. Supports a dry-run preview of the diff before writing.
`create_directory`	Create a directory (and any missing parents). Idempotent: succeeds if the directory already exists.
`list_directory`	List the contents of a directory with file/folder prefixes.
`list_directory_with_sizes`	List directory contents with file sizes and summary stats, sortable by name or size.
`directory_tree`	Return a recursive JSON tree of a directory's structure.
`move_file`	Move or rename a file or directory. Fails if the destination already exists.
`search_files`	Recursively search for files matching a pattern, with optional glob-style exclusion patterns.
`get_file_info`	Return file metadata: size, timestamps, type, and permissions.
`list_allowed_directories`	List the directories the server is permitted to operate on.

Setup Guide

Install and configure

The server runs via npx or Docker. You must pass at least one allowed directory as a CLI argument (or use a client that supports the Roots protocol).

Claude Desktop (NPX)

Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/path/to/other/allowed/dir"
      ]
    }
  }
}

On Windows, use "command": "cmd" with "/c" prefix before npx.

Claude Desktop (Docker)

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--mount", "type=bind,src=/Users/username/Desktop,dst=/projects/Desktop",
        "--mount", "type=bind,src=/path/to/dir,dst=/projects/dir,ro",
        "mcp/filesystem",
        "/projects"
      ]
    }
  }
}

Append ,ro to a mount to make that directory read-only.

VS Code

Run the MCP: Open User Configuration command and add the server to mcp.json, or create .vscode/mcp.json for workspace-scoped configuration. Both NPX and Docker configurations work.

Build Docker image from source

docker build -t mcp/filesystem -f src/filesystem/Dockerfile .

Requirements

Node.js (for the NPX option) or Docker
At least one allowed directory passed as an arg, OR an MCP client that supports the Roots protocol
No API key or authentication needed

Use Cases

Let an AI assistant read and edit code in a specific project directory while preventing it from touching unrelated files on disk
Allow an LLM to scan a folder, summarize file contents, and generate reports across many files using read_multiple_files and directory_tree
Perform bulk find-and-replace or refactor operations across files with edit_file, using dry-run previews before applying changes
Search a codebase or document folder with glob-style patterns to locate files matching a name or extension
Organize a downloads or media directory by moving and renaming files based on metadata extracted by the model

Example Prompts

"List the contents of my Desktop folder and tell me which files were modified today."
"Read all .md files in /Users/me/notes and produce a consolidated summary."
"In my project directory, replace every occurrence of oldApiUrl with newApiUrl, but show me a dry-run diff first."
"Build a directory tree of my repo and identify any files larger than 1 MB."
"Move all PNG files from ~/Downloads into ~/Pictures/screenshots and rename them by date."

Pros

Official reference implementation maintained in the modelcontextprotocol/servers repo, widely supported by MCP clients
Strong sandboxing: operations are restricted to explicitly allowed directories, with read-only mount support via Docker
Comprehensive tool set covering reads, writes, edits with dry-run, search, and metadata
Tool annotations (readOnlyHint, destructive, idempotent) let clients prompt for confirmation on dangerous actions

Limitations

Requires at least one allowed directory at startup, or a client that supports the Roots protocol, otherwise initialization fails
edit_file is non-idempotent and cannot combine head and tail parameters simultaneously
No granular per-file permissions; access control is at the directory level only
Treats files as UTF-8 text by default in read_text_file, which can be awkward for binary or non-UTF-8 content

Alternatives

Git MCP server: same reference repo, scoped to Git repository operations
Desktop Commander MCP: community server that adds shell execution alongside filesystem operations
Native client features like Claude Code or Cursor's built-in file tools, which bypass the need for a separate MCP server when working in an IDE