Filesystem MCP

MCP Server that enables LLMs to interact with the local filesystem. Provides tools for navigation, search, file management, and analysis — all scoped to allowed directories.

Overview

Filesystem MCP exposes a rich set of tools for reading, writing, searching, and inspecting files and directories. All operations are strictly bounded to the directories you provide at startup, preventing access to any path outside those roots.

Key Features

• Navigation: List directory contents (ls), render trees (tree), and query workspace roots (roots).

• File I/O: Read single or multiple files (read, read_many); write, edit, move, and delete (write, edit, mv, rm).

• Search: Find files by glob pattern (find) or search content with full regex support (grep).

• Analysis: Metadata and token estimates (stat, stat_many), SHA-256 hashing (calculate_hash), and unified diffs (diff_files).

• Patch & Replace: Apply unified patches (apply_patch) and bulk search-and-replace across files (search_and_replace).

• Tasks: Long-running tools support background task execution with progress notifications and cancellation.

• Large Output Handling: Oversized results are externalized to ephemeral resource URIs instead of truncating inline.

• Security: Strict path validation, safe regex via RE2, .gitignore-aware operations, and atomic writes.

Requirements

• Node.js >= 24

Quick Start

Run directly:

Client Configuration

Or add manually to .vscode/mcp.json:

CLI:

CLI:

Or add to ~/.cursor/mcp.json:

Add to claude_desktop_config.json:

MCP config:

MCP Surface

Tools

roots — List workspace roots

Enumerate the directories the server is allowed to access. Call this first in any session.

No input parameters.

ls — List directory contents

List immediate directory contents (non-recursive). Returns name, type, size, and modified date per entry.

find — Find files by glob

Locate files matching a glob pattern. Returns relative paths and metadata.

tree — Render directory tree

Returns both an ASCII tree (text) and a structured JSON tree.

read — Read file content

Read text content of a single file with optional line-range or head preview.

Large files return a resourceUri; call resources/read on that URI for full content.

read_many — Read multiple files

Batch-read up to 100 files in a single request.

Per-file truncationReason can be head, range, or externalized. Total read budget is capped internally.

stat — Get file/directory metadata

Returns name, type, size, created/modified/accessed timestamps, permissions, MIME type, and a token estimate (size ÷ 4).

stat_many — Get metadata for multiple paths

Batch version of stat.

grep — Search file content

Search for text within files using literal match or RE2 regex. Returns matching lines with optional context.

calculate_hash — SHA-256 hash

Compute a SHA-256 hash. For directories, produces a deterministic composite hash of all contained files (lexicographically sorted, .gitignore-aware).

diff_files — Generate unified diff

Create a unified diff between two files. Check isIdentical in the response — if true, the files match and no patch is needed.

Large diffs are externalized to a resourceUri.

mkdir — Create directory

Create a directory and all missing parent directories (recursive).

write — Write file

Create or overwrite a file. Parent directories are created automatically.

edit — Edit file

Apply sequential literal string replacements to an existing file. Replaces the first occurrence of each oldText.

Include 3–5 lines of surrounding context in oldText to uniquely target the location. Unmatched edits are reported in unmatchedEdits.

mv — Move or rename

Move or rename a file or directory. Parent directories of the destination are created automatically. Falls back to copy+delete for cross-device moves.

rm — Delete file or directory

Delete a file or directory.

apply_patch — Apply unified patch

Apply a unified diff patch to a file. Always validate with dryRun: true before writing.

If patch application fails, regenerate a fresh patch via diff_files against the current file content and retry.

search_and_replace — Search and replace across files

Replace text in all files matching a glob. Replaces all occurrences per file. Use dryRun: true to preview scope before writing.

Resources

When a tool response includes a resource_link/resourceUri, treat it as authoritative for full payload retrieval and call resources/read with that URI.

Prompts

Tasks (Background Execution)

The server declares full task capabilities (tasks/list, tasks/cancel). The following tools support task-based invocation with progress notifications:

find, tree, read, read_many, stat_many, grep, mkdir, write, mv, rm, calculate_hash, apply_patch, search_and_replace

Include _meta.progressToken in a tools/call request to receive notifications/progress updates. Use tools/call with a task field to invoke as a background task, then poll tasks/get and retrieve output via tasks/result.

Recommended task follow-up loop:

1. Start with tools/call + task (optional _meta.progressToken).

2. Poll tasks/get until terminal status (completed, failed, cancelled).

3. Fetch final payload with tasks/result.

Task status notifications (notifications/tasks/status) are best-effort and emitted only when the transport/runtime provides a notification sender.

Cancellation semantics:

• tasks/cancel is the canonical cancellation API.

• Clients should treat E_CANCELLED as cancellation even if a transport/client surfaces a terminal failure shape.

Configuration

CLI

Examples:

Allowed Directories

Directories are resolved from three sources, merged at runtime:

1. CLI arguments — positional directory paths passed at startup.

2. MCP Roots protocol — directories provided by the connected client after initialization (accepted only if they are within the CLI baseline when CLI directories are set).

3. --allow-cwd — the current working directory is added automatically.

Compatibility

Set FS_CONTEXT_STRIP_STRUCTURED=1 to strip structuredContent from tool results and outputSchema from tool definitions for compatibility with clients that only consume text content.

Security

• Path validation: All operations use isPathWithinDirectories to prevent path traversal attacks.

• Glob safety: Glob patterns are validated to reject absolute paths and .. traversal before execution.

• Safe regex: re2 executes regex (no catastrophic backtracking); safe-regex2 rejects unsafe patterns before use.

• Hidden files: Excluded from listings and searches by default; opt in with includeHidden: true.

• Ignored directories: node_modules, .git, dist, and similar directories are excluded by default; opt in with includeIgnored: true.

• Windows safety: Reserved device names (e.g. CON, NUL, COM1) and drive-relative paths (e.g. C:path) are rejected at the CLI.

• Input limits: Paths are bounded to 4,096 characters; patterns to 1,000 characters.

• Atomic writes: File writes use an atomic write-then-rename strategy to prevent partial writes.

• Docker: The container runs as a non-root user (mcp).

Development

Install

Scripts

MCP Inspector

Or manually:

Build & Release

Releases are triggered manually via GitHub Actions (workflow_dispatch). The pipeline:

1. Bumps package.json and server.json to the selected version (patch / minor / major or custom).

2. Runs lint, type-check, tests, and build.

3. Commits, tags (vX.Y.Z), and creates a GitHub Release with auto-generated notes.

4. Publishes to npm (@j0hanz/filesystem-mcp) with OIDC provenance.

5. Publishes to the MCP Registry (io.github.j0hanz/filesystem-mcp).

6. Builds and pushes the Docker image (ghcr.io/j0hanz/filesystem-mcp) for linux/amd64 and linux/arm64.

The Glama listing requires a separate manual release step on the Glama dashboard.

Docker Build (local)

Troubleshooting

No directories configured If no directories are provided at startup and the client doesn't supply MCP Roots, all tool calls fail with E_ACCESS_DENIED. Use roots to inspect configured roots.

Path outside allowed directories Tools return E_ACCESS_DENIED when a path is outside all allowed roots. Use roots first to see what is available.

Empty directory or no matches find and grep return empty results rather than errors when nothing matches. Verify the pattern and root path.

Pattern rejected ( Glob patterns cannot be absolute or use .. to traverse upward. RE2 patterns are validated before use.

Non-empty directory delete fails rm returns E_INVALID_INPUT for non-empty directories without recursive: true. Either set recursive: true or remove contents first.

Patch application failed apply_patch requires valid unified hunk headers (@@ -N,M +N,M @@). Regenerate the patch with diff_files against the current file content and retry.

Stdout contamination The server uses stdio transport. Never write to stdout in custom integrations. All diagnostic output goes to stderr. For Claude Desktop, check ~/Library/Logs/Claude/mcp*.log (macOS) or the equivalent on Windows.

License

MIT