All TutorialsOVERVIEW
The Filesystem MCP Server is an official reference implementation in the modelcontextprotocol/servers repository. It provides secure file and directory operations for AI assistants through the Model Context Protocol (MCP). According to the Filesystem README, it supports reading and writing files, creating and listing directories, moving files, searching, retrieving metadata, and dynamic access control via MCP Roots.
All install commands and configuration snippets in this tutorial come from the official README at https://github.com/modelcontextprotocol/servers and the Filesystem server documentation at https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem. Do not use unverified third-party install scripts.
WHAT IT DOES
The server publishes fourteen tools, including read_text_file, read_media_file, read_multiple_files, write_file, edit_file (with dryRun preview mode), create_directory, list_directory, list_directory_with_sizes, move_file, search_files, directory_tree, get_file_info, and list_allowed_directories. MCP ToolAnnotations mark read-only tools versus destructive writes so clients can prompt for approval before overwrites.
Access is limited to allowed directories. Specify them as command-line arguments when starting the server, or let a Roots-capable client supply directories at runtime. When Roots are provided, they replace CLI-specified directories entirely per the Filesystem README.
PREREQUISITES
- Node.js 18 or newer
- An MCP client (Claude Desktop, Cursor, Cline, Windsurf, or Warp)
- A directory path you trust the assistant to read and optionally write (for example a single project folder)
Verify installation: node --version
STANDALONE COMMAND (OFFICIAL)
From the modelcontextprotocol/servers README:
npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/dir
You may pass multiple directories as additional arguments. The Filesystem README documents:
mcp-server-filesystem /path/to/dir1 /path/to/dir2
Test in a terminal before adding to your client config. The server stays running on stdio until you stop it.
CLAUDE DESKTOP CONFIGURATION
File location:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
macOS / Linux example from the official Filesystem README (NPX):
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/username/Desktop"
]
}
}
}
WINDOWS NOTE (OFFICIAL)
The main servers README requires wrapping npx with cmd /c on Windows:
{
"mcpServers": {
"filesystem": {
"command": "cmd",
"args": [
"/c",
"npx",
"-y",
"@modelcontextprotocol/server-filesystem",
"C:\Users\username\projects"
]
}
}
}
Use double backslashes in JSON for Windows paths, or forward slashes if you prefer.
CURSOR NOTES
Cursor reads MCP settings from Settings > MCP and/or mcp.json (often ~/.cursor/mcp.json globally or .cursor/mcp.json in a project). Use the same command and args as Claude Desktop. Some builds support a workspace folder variable — check Cursor documentation for your version because UI labels change between releases.
After saving config, restart Cursor or reload MCP servers. Prefer scoping the path to the active repository rather than entire disk volumes.
CLINE NOTES
Open the Cline extension panel, navigate to MCP Servers, and paste the Claude-compatible JSON. Cline invokes Filesystem tools during autonomous coding tasks. Enable tool approval for write_file and edit_file if you want human confirmation before destructive changes.
SECURITY NOTES
The official servers README warns that reference servers are educational examples, not production-hardened services. Grant the smallest directory scope that satisfies your task. Never aim Filesystem at system directories or credential stores. Use edit_file with dryRun true first — the README recommends previewing edits before applying. If the server starts without CLI paths and your client does not support Roots, initialization fails — this is intentional.
FAQ
Q: Where are install commands sourced?
A: https://github.com/modelcontextprotocol/servers README and src/filesystem/README.md.
Q: Can Claude read my entire drive?
A: Only paths you list in args or Roots. Use list_allowed_directories to confirm scope.
Q: Does Fetch replace Filesystem?
A: No. Fetch retrieves remote URLs. Filesystem operates on local allowed directories.
Q: First run is slow?
A: npx downloads @modelcontextprotocol/server-filesystem from npm on first launch.
TROUBLESHOOTING
Quit Claude Desktop completely before testing config changes. Validate JSON (no trailing commas). Run the npx command manually to capture stderr. On Windows ensure cmd /c wrapping is applied only to npx servers, not uvx servers.
NEXT STEPS
Combine with Git MCP for repository history (uvx mcp-server-git --repository path/to/git/repo) or Memory MCP for persistent project notes (npx -y @modelcontextprotocol/server-memory).
DETAILED TOOL WALKTHROUGH
read_text_file supports optional head and tail parameters to read partial files — useful for large logs. read_media_file returns base64-encoded binary with MIME types for images and audio. read_multiple_files batches reads so one tool round-trip covers many paths. write_file overwrites existing files — the ToolAnnotations mark it destructive. edit_file accepts an array of oldText/newText pairs and supports dryRun for preview diffs before mutation. search_files uses glob-style patterns with optional excludePatterns. directory_tree returns indented JSON describing nested structure — ideal for onboarding the model to an unfamiliar repo layout.
DOCKER ALTERNATIVE (FILESYSTEM README)
The Filesystem README also documents Docker-based launch with volume mounts to /projects. That path is advanced and separate from the npx Getting Started flow in the main servers README. Prefer npx until you understand mount semantics and read-only ro flags documented in src/filesystem/README.md.
WHY OFFICIAL COMMANDS MATTER
Third-party blog posts sometimes invent npm package names or stale CLI flags. This tutorial intentionally cites only modelcontextprotocol/servers because that repository is maintained by the MCP steering group alongside SDK authors. When packages update, the README in that repo is the first authoritative source.
VALIDATION CHECKLIST
Before considering your install complete: (1) standalone npx command runs without error, (2) JSON config validates, (3) client restart performed, (4) list_allowed_directories returns your intended path, (5) read_text_file succeeds on a small test file, (6) write operations tested only in a disposable folder.
How to Install the Filesystem MCP Server
Step-by-step: add the Filesystem MCP server to Claude Desktop, Cursor and Cline with a safe, scoped directory.