📌Overview

Purpose: To provide a Node.js server that implements the Model Context Protocol (MCP) for efficient filesystem operations.

Overview: This MCP server facilitates various filesystem operations such as reading and writing files, managing directories, and retrieving file metadata. All operations are restricted to specified directories to ensure safety and control over access.

Key Features:

• File Operations:

  • Read/Write Files: Read complete contents of a file or create/overwrite files safely.

• Directory Management:

  • Create, List, and Delete Directories: Easily manage directories, including creating them as needed and listing their contents.

• File Manipulation:

  • Move Files/Directories: Rename or relocate files and directories while ensuring the destination is valid.

• Search Functionality:

  • Search Files: Recursively search for files and directories based on specified patterns, supporting exclusions.

• Metadata Retrieval:

  • Get File Metadata: Retrieve detailed information about files and directories, including size, creation time, and permissions.

• Advanced Editing:

  • Edit Files: Make selective edits using pattern matching and fuzzy logic, allowing for precise and controlled modifications.

---

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

Note: The server only allows operations within directories specified via args.

API

Resources

• file://system: File system operations interface

Tools

read_file

• Reads complete contents of a file with UTF-8 encoding
• Input: path (string)

read_multiple_files

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

write_file

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

edit_file

• Make selective edits using advanced pattern matching and formatting
• Features include: line-based and multi-line matching, whitespace normalization, multiple simultaneous edits, indentation style detection, Git-style diff output, and dry run mode for preview
• 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 info for dry runs; otherwise applies changes
• Best Practice: Use dryRun first to preview changes before applying

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/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 patterns (supports glob format)
• 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 read/write-accessible directories

Usage with Claude Desktop

Add this to your claude_desktop_config.json:

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

All directories must be mounted to /projects by default.

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

NPX

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

Build

Docker build:

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

License

This MCP server is licensed under the MIT License. You are free to use, modify, and distribute the software under the terms of the MIT License. See the LICENSE file in the project repository for details.