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.

Multi-instance HTTP deployments

Each instance delivers subscriptions/listen change events (resources/updated, tools/list_changed, etc.) on an in-process bus by default. Behind a load balancer with more than one instance, a listener on instance A will not see an event published on instance B. Explicit fleet mode therefore refuses to boot without a shared event bus.

To fan events out across instances, implement the SDK's ServerEventBus interface (two methods: publish/subscribe) over whatever pub/sub you already run, then pass it to filesystem-mcp's programmatic HTTP entry:

import type { ServerEvent, ServerEventBus } from '@modelcontextprotocol/server';

import { startHttpServer } from '@j0hanz/filesystem-mcp/transport';
import Redis from 'ioredis';

// any pub/sub client works the same way

class RedisServerEventBus implements ServerEventBus {
  private readonly listeners = new Set<(event: ServerEvent) => void>();
  private readonly pub = new Redis(process.env['REDIS_URL']);
  private readonly sub = new Redis(process.env['REDIS_URL']);

  constructor() {
    void this.sub.subscribe('fs-mcp-events');
    this.sub.on('message', (_channel, message) => {
      const event = JSON.parse(message) as ServerEvent;
      for (const listener of this.listeners) listener(event);
    });
  }

  publish(event: ServerEvent): void {
    void this.pub.publish('fs-mcp-events', JSON.stringify(event));
  }

  subscribe(listener: (event: ServerEvent) => void): () => void {
    this.listeners.add(listener);
    return () => this.listeners.delete(listener);
  }
}

const eventBus = new RedisServerEventBus();
const apiKey = process.env['FS_API_KEY'];
if (!apiKey) throw new Error('FS_API_KEY is required for a multi-instance HTTP deployment');

await startHttpServer(
  3000,
  { cliAllowedDirs: ['/workspace'] },
  { apiKey, eventBus, deploymentMode: 'fleet' },
);

This project ships no bus adapter and no pub/sub dependency. A single in-process instance (the common case) needs nothing extra and is the CLI's default. Load-balanced deployments must use the programmatic API with deploymentMode: 'fleet'.

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 node scripts/tasks.mjs 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.