Filesystem MCP

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

1. Clone the repository

2. Install dependencies:

   npm ci
   

3. Build the project:

   npm run build
   

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

<details> <summary><strong>Claude Desktop</strong></summary>

Add to your claude_desktop_config.json:

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

</details>

<details> <summary><strong>Cursor</strong></summary>

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

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

</details>

<details> <summary><strong>VS Code</strong></summary>

Add to your .vscode/mcp.json:

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

</details>

<details> <summary><strong>Docker (any MCP client)</strong></summary>

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"
      ]
    }
  }
}

</details>

<details> <summary><strong>Codex</strong></summary>

Add to your configuration:

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

</details>

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

1. Install Dependencies:

   npm install
   

2. Development Mode (watch):

   npm run dev
   

3. Run Locally:

   npm start -- --allow-cwd
   

4. Test:

   npm run test
   

5. Lint & Format:

   npm run lint
   npm run format
   

License

MIT