servers/src/filesystem at main · modelcontextprotocol/servers · GitHub

===============

Skip to content Navigation Menu

Toggle navigation

Sign in

Appearance settings

• Product

*   [GitHub Copilot Write better code with AI](https://github.com/features/copilot)
*   [GitHub Spark New Build and deploy intelligent apps](https://github.com/features/spark)
*   [GitHub Models New Manage and compare prompts](https://github.com/features/models)
*   [GitHub Advanced Security Find and fix vulnerabilities](https://github.com/security/advanced-security)
*   [Actions Automate any workflow](https://github.com/features/actions)

*   [Codespaces Instant dev environments](https://github.com/features/codespaces)
*   [Issues Plan and track work](https://github.com/features/issues)
*   [Code Review Manage code changes](https://github.com/features/code-review)
*   [Discussions Collaborate outside of code](https://github.com/features/discussions)
*   [Code Search Find more, search less](https://github.com/features/code-search)

Explore * Why GitHub * All features * Documentation * GitHub Skills * Blog

• Solutions

By company size * Enterprises * Small and medium teams * Startups * Nonprofits

By use case * DevSecOps * DevOps * CI/CD * View all use cases

By industry * Healthcare * Financial services * Manufacturing * Government * View all industries

View all solutions

• Resources

Topics * AI * DevOps * Security * Software Development * View all

Explore * Learning Pathways * Events & Webinars * Ebooks & Whitepapers * Customer Stories * Partners * Executive Insights

• Open Source

*   [GitHub Sponsors Fund open source developers](https://github.com/sponsors)

*   [The ReadME Project GitHub community articles](https://github.com/readme)

Repositories * Topics * Trending * Collections

• Enterprise

*   [Enterprise platform AI-powered developer platform](https://github.com/enterprise)

Available add-ons * GitHub Advanced Security Enterprise-grade security features * Copilot for business Enterprise-grade AI features * Premium Support Enterprise-grade 24/7 support

• Pricing

Search or jump to...

Search code, repositories, users, issues, pull requests...

Search

Clear

Search syntax tips

Provide feedback

We read every piece of feedback, and take your input very seriously.

• [x] Include my email address so I can be contacted

Cancel Submit feedback

Saved searches

Use saved searches to filter your results more quickly

Name

Query

To see all available qualifiers, see our documentation.

Cancel Create saved search

Sign in

Sign up

Appearance settings

Resetting focus

You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert

{{ message }}

modelcontextprotocol/**servers**Public

• NotificationsYou must be signed in to change notification settings

• Fork 7.3k

• Star 62.6k

• Code

• Issues 198

• Pull requests 150

• Actions

• Security 2### Uh oh! There was an error while loading.Please reload this page.

• Insights

Additional navigation options

• Code
• Issues
• Pull requests
• Actions
• Security
• Insights

Collapse file tree

Files

main

Search this repository

•     .github  
  

•     .vscode  
  

•     scripts  
  

•     src  
  

  •      everything  
    

  •      fetch  
    

  •      filesystem  
    

    •        __tests__   
      

    •     Dockerfile  
      

    •     README.md  
      

    •     index.ts  
      

    •     jest.config.cjs  
      

    •     package.json  
      

    •     path-utils.ts  
      

    •     path-validation.ts  
      

    •     roots-utils.ts  
      

    •     tsconfig.json  
      

  •      git  
    

  •      memory  
    

  •      sequentialthinking  
    

  •      time  
    

•   .gitattributes  
  

•   .gitignore  
  

•   .npmrc  
  

•   CODE_OF_CONDUCT.md  
  

•   CONTRIBUTING.md  
  

•   LICENSE  
  

•   README.md  
  

•   SECURITY.md  
  

•   package-lock.json  
  

•   package.json  
  

•   tsconfig.json  
  

Breadcrumbs

1. servers
2. /src

/ filesystem

/

Copy path

Directory actions

More options

More options

Directory actions

More options

More options

Latest commit

vksampath

Update src/filesystem/README.md

Open commit details

Jul 26, 2025

a688cca·Jul 26, 2025

History

History

Open commit details

Breadcrumbs

1. servers
2. /src

/ filesystem

/

Top

Folders and files

Name	Name	Last commit message	Last commit date
### parent directory ..
tests	tests	feat(filesystem): implement MCP roots protocol for dynamic directory …	Jul 1, 2025
Dockerfile	Dockerfile	fix warnings: - FromAsCasing: 'as' and 'FROM' keywords' casing do not…	Jan 2, 2025
README.md	README.md	Update src/filesystem/README.md	Jul 26, 2025
index.ts	index.ts	Replace read_file tool with deprecation notice in description, whic…	Jul 25, 2025
jest.config.cjs	jest.config.cjs	Add working test config for filesystem	Apr 14, 2025
package.json	package.json	Update SDK version	Jul 24, 2025
path-utils.ts	path-utils.ts	Handle unc path	Jun 20, 2025
path-validation.ts	path-validation.ts	Address symlink and path prefix issues with allowed directories	Jul 1, 2025
roots-utils.ts	roots-utils.ts	feat(filesystem): add symlink resolution and home directory support t…	Jul 2, 2025
tsconfig.json	tsconfig.json	Updated Filesystem	Nov 21, 2024
View all files

README.md

Outline

Filesystem MCP Server

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

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:

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

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 (or provides empty roots), the server will throw an error during initialization.

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
*   **On runtime updates**: Client can send `notifications/roots/list_changed`
*   Server requests updated roots and replaces allowed directories again

4. Fallback Behavior (if client doesn't support roots)

*   Server continues using command-line directories only
*   No dynamic updates possible

5. Access Control

*   All filesystem operations are restricted to allowed directories
*   Use `list_allowed_directories` tool to see current directories
*   Server requires at least ONE allowed directory to operate

Note: The server will only allow operations within directories specified either via args or via Roots.

API

Resources

• file://system: File system operations interface

Tools

• read_text_file

  • Read complete contents of a file as text

  • Inputs:

    • path (string)
    • head (number, optional): First N lines
    • tail (number, optional): Last N lines

  • Always treats the file as UTF-8 text regardless of extension

• read_media_file

  • Read an image or audio file

  • Inputs:

    • path (string)

  • Streams the file and returns base64 data with the corresponding MIME type

• read_multiple_files

  • Read multiple files simultaneously
  • Input: paths (string[])
  • Failed reads won't stop the entire operation

• write_file

  • Create new file or overwrite existing (exercise caution with this)
  • Inputs:
    • path (string): File location
    • content (string): File content

• edit_file

  • Make selective edits using advanced pattern matching and formatting

  • Features:

    • Line-based and multi-line content matching
    • Whitespace normalization with indentation preservation
    • Multiple simultaneous edits with correct positioning
    • Indentation style detection and preservation
    • Git-style diff output with context
    • Preview changes with dry run mode

  • Inputs:

    • path (string): File to edit

    • edits (array): List of edit operations

      • oldText (string): Text to search for (can be substring)
      • newText (string): Text to replace with

    • dryRun (boolean): Preview changes without applying (default: false)

  • Returns detailed diff and match information for dry runs, otherwise applies changes

  • Best Practice: Always use dryRun first to preview changes before applying them

• create_directory

  • Create new directory or ensure it exists
  • Input: path (string)
  • Creates parent directories if needed
  • Succeeds silently if directory exists

• list_directory

  • List directory contents with [FILE] or [DIR] prefixes
  • Input: path (string)

• move_file

  • Move or rename files and directories

  • Inputs:

    • source (string)
    • destination (string)

  • Fails if destination exists

• search_files

  • Recursively search for files/directories

  • Inputs:

    • path (string): Starting directory
    • pattern (string): Search pattern
    • excludePatterns (string[]): Exclude any patterns. Glob formats are supported.

  • Case-insensitive matching

  • Returns full paths to matches

• get_file_info

  • Get detailed file/directory metadata
  • Input: path (string)
  • Returns:
    • Size
    • Creation time
    • Modified time
    • Access time
    • Type (file/directory)
    • Permissions

• list_allowed_directories

  • List all directories the server is allowed to access
  • No input required
  • Returns:
    • Directories that this server can read/write from

Usage with Claude Desktop

Add this to your claude_desktop_config.json:

Note: you can provide sandboxed directories to the server by mounting them to /projects. Adding the ro flag will make the directory readonly by the server.

Docker

Note: all directories must be mounted to /projects by default.

undefinedjson { "mcpServers": { "filesystem": { "command": "docker", "args": [ "run", "-i", "--rm", "--mount", "type=bind,src=/Users/username/Desktop,dst=/projects/Desktop", "--mount", "type=bind,src=/path/to/other/allowed/dir,dst=/projects/other/allowed/dir,ro", "--mount", "type=bind,src=/path/to/file.txt,dst=/projects/path/to/file.txt", "mcp/filesystem", "/projects" ] } } } undefined

NPX

undefinedjson { "mcpServers": { "filesystem": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-filesystem", "/Users/username/Desktop", "/path/to/other/allowed/dir" ] } } } undefined

Usage with VS Code

For quick installation, click the installation buttons below...

For manual installation, add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing Ctrl + Shift + P and typing Preferences: Open Settings (JSON).

Optionally, you can add it to a file called .vscode/mcp.json in your workspace. This will allow you to share the configuration with others.

Note that the mcp key is not needed in the .vscode/mcp.json file.

You can provide sandboxed directories to the server by mounting them to /projects. Adding the ro flag will make the directory readonly by the server.

Docker

Note: all directories must be mounted to /projects by default.

undefinedjson { "mcp": { "servers": { "filesystem": { "command": "docker", "args": [ "run", "-i", "--rm", "--mount", "type=bind,src=${workspaceFolder},dst=/projects/workspace", "mcp/filesystem", "/projects" ] } } } } undefined

NPX

undefinedjson { "mcp": { "servers": { "filesystem": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-filesystem", "${workspaceFolder}" ] } } } } undefined

Build

Docker build:

undefinedshell docker build -t mcp/filesystem -f src/filesystem/Dockerfile . undefined

License

This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.

Footer

© 2025 GitHub,Inc.

Footer navigation

• Terms
• Privacy
• Security
• Status
• Docs
• Contact
• Manage cookies
• Do not share my personal information

You can’t perform that action at this time.