Filesystem MCP

npm version License Node.js Version

MCP Server that enables LLMs to interact with the local filesystem. Provides tools for navigation, file management, searching, and analysis, all within a secure, allowed set of directories. Ideal for agents needing to read/write files, explore directory structures, or perform file operations as part of their tasks.

Key Features

Navigation: List directories (ls), view trees (tree), and discover workspace roots (roots).
File Management: Create (mkdir), write (write), edit (edit), move (mv), and delete (rm) files/directories.
Search: Find files by glob pattern (find) or search content using regex (grep).
Analysis: Inspect metadata (stat), calculate hashes (calculate_hash), and compare files (diff_files).
Batch Operations: Read multiple files (read_many) or replace text across many files (search_and_replace).
Security: Strictly scoped to allowed directories provided at startup.

Tech Stack

Runtime: Node.js >= 24
Language: TypeScript
SDK: @modelcontextprotocol/sdk
Libraries: zod, commander, re2, diff

Repository Structure

.
├── src/
│   ├── index.ts        # Entry point
│   ├── server.ts       # MCP Server implementation
│   ├── tools/          # Individual tool implementations
│   └── lib/            # Shared utilities
├── assets/             # Images and static resources
├── scripts/            # Build and maintenance scripts
└── package.json

Requirements

Node.js >= 24

Quickstart

Run directly with npx:

npx -y @j0hanz/filesystem-mcp@latest "C:\path\to\allowed\directory"

Installation

NPX (Recommended)

npx -y @j0hanz/filesystem-mcp@latest [options] [directories...]

Docker

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

Mount host directories as volumes to /projects/ and pass the container paths as arguments.

From Source

Clone the repository
Install dependencies:
```
npm ci
```
Build the project:
```
npm run build
```

Run:

node dist/index.js [options] [directories...]

Configuration

The server requires specifying allowed directories via command-line arguments.

Arguments

Argument	Description
`[allowedDirs...]`	Positional arguments specifying the root directories the server can access.

Options

Option	Description
`--allow-cwd`	Allow the current working directory as an additional root.
`-v, --version`	Display server version.
`-h, --help`	Display command help.

Usage

Stdio Transport

The server communicates via stdio. Ensure your MCP client is configured to run the server command and capture standard input/output.

MCP Surface

Tools

Tool	Description	Key Parameters
`roots`	List allowed workspace roots	None
`ls`	List directory contents	`path`, `includeHidden`
`find`	Find files by glob pattern	`pattern`, `path`, `maxDepth`
`tree`	Generate directory tree	`path`, `maxDepth`
`read`	Read file content	`path`, `head`
`read_many`	Read multiple files	`paths`
`grep`	Search file content (regex/literal)	`pattern`, `path`, `isRegex`
`stat`	Get file metadata	`path`
`stat_many`	Get metadata for multiple files	`paths`
`calculate_hash`	Calculate SHA-256 hash	`path`
`mkdir`	Create directory (recursive)	`path`
`write`	Write file (create/overwrite)	`path`, `content`
`edit`	Edit file (string replacement)	`path`, `edits`
`mv`	Move or rename file/directory	`source`, `destination`
`rm`	Delete file or directory	`path`, `recursive`
`diff_files`	Generate unified diff	`original`, `modified`
`apply_patch`	Apply unified patch	`path`, `patch`
`search_and_replace`	Search & replace across files	`filePattern`, `searchPattern`, `replacement`

Resources

URI Pattern	Description
`internal://instructions`	Usage guidance and documentation
`filesystem-mcp://result/{id}`	Ephemeral cached tool output (for large results)

Prompts

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

Client Configuration Examples

Claude Desktop

Add to your claude_desktop_config.json:

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

Cursor

Add to your .cursor/mcp.json or configure via UI:

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

VS Code

Add to your .vscode/mcp.json:

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

Docker (any MCP client)

Use the Docker image with any MCP client that supports stdio transport:

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

Codex

Add to your configuration:

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

Security

Path Restrictions: All file operations are strictly validated against the allowed root directories provided at startup.
Path Validation: Uses isPathWithinDirectories to prevent path traversal attacks.
Hidden Files: Hidden files (starting with .) are excluded by default in listings and searches unless explicitly requested.

Development Workflow

Install Dependencies:
```
npm install
```
Development Mode (watch):
```
npm run dev
```
Run Locally:
```
npm start -- --allow-cwd
```
Test:
```
npm run test
```
Lint & Format:
```
npm run lint
npm run format
```

License

MIT

Filesystem MCP

Quick Install

Filesystem MCP

Key Features

Tech Stack

Repository Structure

Requirements

Quickstart

Installation

NPX (Recommended)

Docker

From Source

Configuration

Arguments

Options

Usage

Stdio Transport

MCP Surface

Tools

Resources

Prompts

Client Configuration Examples

Security

Development Workflow

License

Reviews