MCP filesystem (reference)

Filesystem MCP Server

Node.js server implementing Model Context Protocol (MCP) for filesystem operations.

Published on npm as @modelcontextprotocol/server-filesystem.

Features

• Read/write files
• Create/list/delete directories
• Move files/directories
• Search files
• Get file metadata
• Dynamic directory access control via Roots

Directory Access Control

The server uses a flexible directory access control system. Directories can be specified via command-line arguments or dynamically via Roots.

Method 1: Command-line Arguments

Specify Allowed directories when starting the server:

mcp-server-filesystem /path/to/dir1 /path/to/dir2

Method 2: MCP Roots (Recommended)

MCP clients that support Roots can dynamically update the Allowed directories.

Roots notified by Client to Server, completely replace any server-side Allowed directories when provided.

Important: If server starts without command-line arguments AND client doesn't support roots protocol, the server fails at initialization: it logs the reason to stderr, closes the connection and exits with status 1. A client that supports roots but provides none (or none that are valid) keeps the connection, with no allowed directories until it sends roots/list_changed with valid roots.

This is the recommended method, as this enables runtime directory updates via roots/list_changed notifications without server restart, providing a more flexible and modern integration experience.

How It Works

The server's directory access control follows this flow:

1. Server Startup

   • Server starts with directories from command-line arguments (if provided)
   • If no arguments provided, server starts with empty allowed directories

2. Client Connection & Initialization

   • Client connects and sends initialize request with capabilities
   • Server checks if client supports roots protocol (capabilities.roots)

3. Roots Protocol Handling (if client supports roots)

   • On initialization: Server requests roots from client via roots/list
   • Client responds with its configured roots
   • Server replaces ALL allowed directories with client's roots
   • Tool calls that arrive before the initial roots are loaded wait for them, so they are checked against the client's roots
   • On runtime updates: Client can send notifications/roots/list_changed
   • Server requests updated roots and replaces allowed directories again
   • Tool calls that arrive while an update is being fetched wait for it, so none runs against a root the client has just withdrawn
   • Once the client's roots are in force, an update with no valid roots revokes access: every path is refused ("Access denied - no allowed directories") until the client exposes a root again. Before any root has been in force, such an update keeps the command-line directories