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

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/allowed/dir"]
    }
  }
}

Run directly:

npx -y @j0hanz/filesystem-mcp@latest /path/to/allowed/dir

Client Configuration

Install in VS Code

Or add manually to .vscode/mcp.json:

{
  "servers": {
    "filesystem-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "${workspaceFolder}"]
    }
  }
}

CLI:

code --add-mcp '{"name":"filesystem-mcp","command":"npx","args":["-y","@j0hanz/filesystem-mcp@latest","${workspaceFolder}"]}'

Install in VS Code Insiders

CLI:

code-insiders --add-mcp '{"name":"filesystem-mcp","command":"npx","args":["-y","@j0hanz/filesystem-mcp@latest","${workspaceFolder}"]}'

Install in Cursor

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

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/dir"]
    }
  }
}

Install in Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/dir"]
    }
  }
}

Install in Claude Code

claude mcp add filesystem-mcp -- npx -y @j0hanz/filesystem-mcp@latest /path/to/dir

Install in Windsurf

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/dir"]
    }
  }
}

Install in Codex

[mcp_servers.filesystem-mcp]
command = "npx"
args = ["-y", "@j0hanz/filesystem-mcp@latest", "${workspaceFolder}"]

Docker

docker run -i --rm \
  -v /path/to/your/project:/projects/workspace:ro \
  ghcr.io/j0hanz/filesystem-mcp:latest \
  /projects/workspace

MCP config:

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/project:/projects/workspace:ro",
        "ghcr.io/j0hanz/filesystem-mcp:latest",
        "/projects/workspace"
      ]
    }
  }
}

MCP Surface

Tools

Tool	Description
`roots`	List workspace roots the server can access
`ls`	List directory contents (non-recursive)
`find`	Find files by glob pattern
`tree`	Render a bounded directory tree
`read`	Read text content of a file
`read_many`	Read multiple files in one request
`stat`	Get file or directory metadata
`stat_many`	Get metadata for multiple paths
`grep`	Search file content by literal or RE2 regex
`calculate_hash`	Compute SHA-256 hash of a file or directory
`diff_files`	Generate a unified diff between two files
`mkdir`	Create a directory (recursive)
`write`	Write content to a file (create or overwrite)
`edit`	Edit a file via sequential string replacements
`mv`	Move or rename a file or directory
`rm`	Delete a file or directory
`apply_patch`	Apply a unified diff patch to a file
`search_and_replace`	Search and replace text across files matching a glob

`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.

Parameter	Type	Required	Default	Description
`path`	string	No	root	Base directory
`includeHidden`	boolean	No	`false`	Include hidden items (`.`)
`includeIgnored`	boolean	No	`false`	Include `node_modules`, `.git`, etc.
`pattern`	string	No	—	Glob filter enabling recursive traversal (e.g. `*/.ts`)
`sortBy`	`name`\|`size`\|`modified`\|`type`	No	`name`	Sort field
`maxDepth`	integer	No	—	Max recursion depth when `pattern` is set (1–50)
`maxEntries`	integer	No	—	Truncation limit (1–20,000)
`includeSymlinkTargets`	boolean	No	`false`	Resolve and include symlink targets

`find` — Find files by glob

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

Parameter	Type	Required	Default	Description
`pattern`	string	Yes	—	Glob pattern (e.g. `*/.ts`, `src/*.js`)
`path`	string	No	root	Search root
`maxResults`	integer	No	`100`	Max results (1–10,000)
`maxDepth`	integer	No	—	Max directory depth to scan (0–100)
`sortBy`	`name`\|`size`\|`modified`\|`path`	No	`path`	Sort field
`includeHidden`	boolean	No	`false`	Include hidden files
`includeIgnored`	boolean	No	`false`	Include ignored directories (disables `.gitignore`)

Tip

Supports background task execution with progress reporting.

`tree` — Render directory tree

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

Parameter	Type	Required	Default	Description
`path`	string	No	root	Base directory
`maxDepth`	integer	No	`5`	Max depth (0–50); `0` = root node only, no children
`maxEntries`	integer	No	`1000`	Max entries (1–20,000)
`includeHidden`	boolean	No	`false`	Include hidden items
`includeIgnored`	boolean	No	`false`	Include ignored items (disables `.gitignore`)

`read` — Read file content

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

Parameter	Type	Required	Default	Description
`path`	string	Yes	—	Absolute path to file
`head`	integer	No	—	Read first N lines (1–100,000); mutually exclusive with `startLine`/`endLine`
`startLine`	integer	No	—	Start line (1-based, inclusive)
`endLine`	integer	No	—	End line (1-based, inclusive); requires `startLine`

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.

Parameter	Type	Required	Default	Description
`paths`	string[]	Yes	—	File paths (1–100 items)
`head`	integer	No	—	Read first N lines of each file
`startLine`	integer	No	—	Start line per file
`endLine`	integer	No	—	End line per file (requires `startLine`)

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).

Parameter	Type	Required	Default	Description
`path`	string	Yes	—	Absolute path

`stat_many` — Get metadata for multiple paths

Batch version of stat.

Parameter	Type	Required	Default	Description
`paths`	string[]	Yes	—	Paths (1–100 items)

`grep` — Search file content

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

Parameter	Type	Required	Default	Description
`pattern`	string	Yes	—	Text to search (literal by default, RE2 regex when `isRegex: true`)
`path`	string	No	root	Search root (file or directory)
`isRegex`	boolean	No	`false`	Treat `pattern` as RE2 regex
`caseSensitive`	boolean	No	`false`	Case-sensitive matching
`wholeWord`	boolean	No	`false`	Match whole words only
`contextLines`	integer	No	`0`	Lines of context before/after each match (0–50)
`maxResults`	integer	No	`500`	Max match rows returned (0–10,000)
`filePattern`	string	No	`*/`	Glob to restrict candidate files (e.g. `*/.ts`)
`includeHidden`	boolean	No	`false`	Include hidden files
`includeIgnored`	boolean	No	`false`	Include ignored directories

Note

RE2 does not support lookahead, lookbehind, or backreferences. Results exceeding 50 inline matches are externalized via resourceUri.

`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).

Parameter	Type	Required	Default	Description
`path`	string	Yes	—	File or directory path

`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.

Parameter	Type	Required	Default	Description
`original`	string	Yes	—	Original file path
`modified`	string	Yes	—	Modified file path
`context`	integer	No	—	Lines of context in the diff
`ignoreWhitespace`	boolean	No	`false`	Ignore leading/trailing whitespace
`stripTrailingCr`	boolean	No	`false`	Strip trailing carriage returns

Large diffs are externalized to a resourceUri.

`mkdir` — Create directory

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

Parameter	Type	Required	Default	Description
`path`	string	Yes	—	Directory path to create

`write` — Write file

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

Parameter	Type	Required	Default	Description
`path`	string	Yes	—	File path
`content`	string	Yes	—	Content to write

Caution

Overwrites existing file content without confirmation.

`edit` — Edit file

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

Parameter	Type	Required	Default	Description
`path`	string	Yes	—	File to edit
`edits`	`{oldText, newText}[]`	Yes	—	Ordered list of replacement operations
`dryRun`	boolean	No	`false`	Validate edits without writing

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.

Parameter	Type	Required	Default	Description
`source`	string	Yes	—	Source path
`destination`	string	Yes	—	Destination path

`rm` — Delete file or directory

Delete a file or directory.

Parameter	Type	Required	Default	Description
`path`	string	Yes	—	Path to delete
`recursive`	boolean	No	`false`	Delete non-empty directories
`ignoreIfNotExists`	boolean	No	`false`	No error if the path is missing

Warning

Non-empty directories with recursive: false return E_INVALID_INPUT with guidance to retry using recursive: true.

`apply_patch` — Apply unified patch

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

Parameter	Type	Required	Default	Description
`path`	string	Yes	—	Target file path
`patch`	string	Yes	—	Unified diff patch content (must include hunk headers)
`fuzzFactor`	integer	No	`0`	Fuzzy matching tolerance
`autoConvertLineEndings`	boolean	No	`true`	Auto-convert line endings to match the target file
`dryRun`	boolean	No	`false`	Validate without 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.

Parameter	Type	Required	Default	Description
`filePattern`	string	Yes	—	Glob for target files (e.g. `*/.ts`)
`searchPattern`	string	Yes	—	Text to find
`replacement`	string	Yes	—	Replacement text
`path`	string	No	root	Search root directory
`isRegex`	boolean	No	`false`	Treat `searchPattern` as RE2 regex; supports capture groups (`$1`, `$2`)
`dryRun`	boolean	No	`false`	Preview matches without writing

Resources

URI	Description	MIME Type
`internal://instructions`	Usage guidance for models	`text/markdown`
`filesystem-mcp://result/{id}`	Ephemeral cached large tool output	varies

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

Prompt	Description
`get-help`	Returns usage instructions for the server

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:

Start with tools/call + task (optional _meta.progressToken).
Poll tasks/get until terminal status (completed, failed, cancelled).
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

filesystem-mcp [options] [allowedDirs...]

Option	Description
`[allowedDirs...]`	Positional: one or more directories the server may access
`--allow-cwd`	Allow the current working directory as an additional root
`-v, --version`	Display server version
`-h, --help`	Display help

Examples:

# Single directory
filesystem-mcp /project/src

# Multiple directories
filesystem-mcp /project/src /project/tests

# Current working directory
filesystem-mcp --allow-cwd

# Combined
filesystem-mcp /project/src --allow-cwd

Allowed Directories

Directories are resolved from three sources, merged at runtime:

CLI arguments — positional directory paths passed at startup.
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).
--allow-cwd — the current working directory is added automatically.

Tip

If no directories are configured at startup and the connected client does not supply MCP Roots, all tool calls will fail. Pass at least one directory argument or use --allow-cwd.

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).

Important

All diagnostic output goes to stderr. Tool handlers must never write to stdout, as doing so would corrupt the stdio transport.

Development

Install

npm ci

Scripts

Script	Command	Purpose
`dev`	`tsc --watch`	Watch-mode TypeScript compilation
`dev:run`	`node --watch dist/index.js`	Run built server with file watching
`build`	`node scripts/tasks.mjs build`	Production build
`test`	`node scripts/tasks.mjs test`	Run full test suite
`test:fast`	`node --test --import tsx/esm src/__tests__/*/.test.ts`	Fast test runner (no build step)
`test:coverage`	`node scripts/tasks.mjs test --coverage`	Test with coverage
`lint`	`eslint .`	Lint source files
`lint:fix`	`eslint . --fix`	Auto-fix lint issues
`format`	`prettier --write .`	Format all files
`type-check`	`node scripts/tasks.mjs type-check`	TypeScript type checking

MCP Inspector

npm run inspector

Or manually:

npx @modelcontextprotocol/inspector node dist/index.js /path/to/dir

Build & Release

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

Bumps package.json and server.json to the selected version (patch / minor / major or custom).
Runs lint, type-check, tests, and build.
Commits, tags (vX.Y.Z), and creates a GitHub Release with auto-generated notes.
Publishes to npm (@j0hanz/filesystem-mcp) with OIDC provenance.
Publishes to the MCP Registry (io.github.j0hanz/filesystem-mcp).
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)

docker build -t filesystem-mcp .

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 (E_INVALID_PATTERN) 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

Name		Name	Last commit message	Last commit date
Latest commit History 535 Commits
.github/workflows		.github/workflows
assets		assets
node-tests		node-tests
scripts		scripts
src		src
.dockerignore		.dockerignore
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
AGENTS.md		AGENTS.md
Dockerfile		Dockerfile
README.md		README.md
docker-compose.yml		docker-compose.yml
eslint.config.mjs		eslint.config.mjs
glama.json		glama.json
knip.json		knip.json
package-lock.json		package-lock.json
package.json		package.json
server.json		server.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
tsconfig.test.json		tsconfig.test.json

j0hanz/filesystem-mcp

Folders and files

Latest commit

History

Repository files navigation

Filesystem MCP

Overview

Key Features

Requirements

Quick Start

Client Configuration

MCP Surface

Tools

roots — List workspace roots

ls — List directory contents

find — Find files by glob

tree — Render directory tree

read — Read file content

read_many — Read multiple files

stat — Get file/directory metadata

stat_many — Get metadata for multiple paths

grep — Search file content

calculate_hash — SHA-256 hash

diff_files — Generate unified diff

mkdir — Create directory

write — Write file

edit — Edit file

mv — Move or rename

rm — Delete file or directory

apply_patch — Apply unified patch

search_and_replace — Search and replace across files

Resources

Prompts

Tasks (Background Execution)

Configuration

CLI

Allowed Directories

Compatibility

Security

Development

Install

Scripts

MCP Inspector

Build & Release

Docker Build (local)

Troubleshooting

License

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases 19

Packages 0

Uh oh!

Contributors 3

Uh oh!

Languages

`roots` — List workspace roots

`ls` — List directory contents

`find` — Find files by glob

`tree` — Render directory tree

`read` — Read file content

`read_many` — Read multiple files

`stat` — Get file/directory metadata

`stat_many` — Get metadata for multiple paths

`grep` — Search file content

`calculate_hash` — SHA-256 hash

`diff_files` — Generate unified diff

`mkdir` — Create directory

`write` — Write file

`edit` — Edit file

`mv` — Move or rename

`rm` — Delete file or directory

`apply_patch` — Apply unified patch

`search_and_replace` — Search and replace across files

Packages