Filesystem MCP

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

Options

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

Resources

Prompts

Client Configuration Examples

Add to your claude_desktop_config.json:

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

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

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

Add to your .vscode/mcp.json:

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

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

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

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