Filesystem MCP Server

Overview

Filesystem-MCP is a Model Context Protocol server that lets AI assistants read and write files within explicitly allowed directories. Sensitive file patterns (.env, *.pem, *id_rsa*) are blocked by default. It exposes filesystem tools, resources, and prompts over stdio or Streamable HTTP transport.

Features

Built with

Table of Contents

• Quick start
• Usage
• Project structure
• Configuration
• Scripts
• Security
• Contributing
• License

Quick start

[!NOTE] Requires Node.js ≥ 24.

Prerequisites

Install via npx

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

Or install globally:

npm install -g @j0hanz/filesystem-mcp
filesystem-mcp /path/to/allowed/dir

Install via Docker

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

Configure in VS Code

Add to .vscode/mcp.json:

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

Or install via CLI:

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

Configure in Visual Studio

Add to .vs\mcp.json in your solution directory, or %USERPROFILE%\.mcp.json for a global configuration:

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

Configure in Claude Desktop

Add to your claude_desktop_config.json:

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

Install in Cursor

Add to .cursor/mcp.json in your project root (project-scoped), or ~/.cursor/mcp.json for a global configuration:

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

Docker configuration

VS Code (.vscode/mcp.json) and Visual Studio (.vs\mcp.json):

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

Claude Desktop (claude_desktop_config.json) and Cursor (mcp.json):

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

[!NOTE] For least privilege, use both controls: :ro makes the container mount read-only at the operating-system boundary, while the server's --read-only flag removes mutating tools (create, edit, move, delete, patch, replace_text) from tools/list.

Usage

Tools

All tools are scoped to the configured roots. Call list_roots first to discover what is allowed.

Navigate

Inspect

Read

Write

Resources

Prompts

Project structure

filesystem-mcp/
├── __tests__/        Test suites
├── scripts/          Build and task utilities
├── src/
│   ├── core/         Path guarding, filesystem abstraction, concurrency, observability
│   ├── tools/        Tool definitions and registration
│   ├── index.ts      Process entrypoint and transport selection
│   ├── server.ts     Server factory and registrar composition
│   ├── transport/    stdio and Streamable HTTP transport setup
│   ├── prompts.ts    Prompt definitions and registration
│   └── resources.ts  Resource definitions and registration
└── Dockerfile        Multi-stage alpine build, non-root user

Runtime composition flows from src/index.ts to src/transport.ts, then to src/server.ts, the registrars, and finally src/core/. Each registrar owns the narrow dependency contract it consumes.

Configuration

The server starts with allowed directories from explicit startup configuration:

1. Positional directories passed to filesystem-mcp.
2. Environment variable FS_ALLOWED_DIRS (separated by : on POSIX or ; on Windows).
3. Current working directory when --allow-cwd is enabled.

Legacy MCP connections may additionally seed roots through the deprecated roots/list flow. Modern 2026-07-28 connections do not automatically send workspace roots. They can add access after startup by calling a tool with a concrete path and approving the elicitation-backed grant. list_roots reports the roots already configured or accepted; it cannot discover an unknown workspace by itself.

Recommended global recipes

VS Code / Cursor / Claude Code (primary recipe)

Configure the project directory explicitly:

Add to your global or project-scoped configuration:

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

Claude Desktop (fallback recipe via environment variable)

Claude Desktop and similar clients don't support the MCP Roots protocol. Use the FS_ALLOWED_DIRS environment variable to configure allowed folders.

Add to your claude_desktop_config.json:

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

(On Windows, separate directories with a semicolon ; instead of a colon :).

Advanced / per-project positional arguments

You can also restrict access to specific directories by passing positional arguments directly:

# Start with explicit positional paths
filesystem-mcp /path/to/project1 /path/to/project2

Configuration reference

CLI flags

Environment variables

All boolean variables accept true or 1 to enable and false, 0, or unset to disable; any other value logs a warning and reads as disabled. Flags take precedence when both are set.

Examples

# Allow current working directory
filesystem-mcp --allow-cwd

# HTTP transport on port 3000
filesystem-mcp --port 3000

Scripts

Security

[!IMPORTANT] Report vulnerabilities privately via GitHub Security Advisories. Do not open public issues for security reports.

Contributing

1. Fork the repository.
2. Create a feature branch: git checkout -b feat/your-feature.
3. Commit your changes with a clear message.
4. Run npm run check to confirm tests, types, lint, formatting, and knip all pass.
5. Open a pull request.

License

Released under the MIT License. See LICENSE for details.