📌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

A Node.js server implementing the 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 allows operations only within specified directories via args.

API

Resources

• file://system: File system operations interface

Tools

• read_file

  • Reads the complete contents of a file.
  • Input: path (string).

• read_multiple_files

  • Reads multiple files simultaneously.
  • Input: paths (string[]).

• write_file

  • Creates a new file or overwrites an existing one.
  • Inputs:
    • path (string): File location.
    • content (string): File content.

• edit_file

  • Makes selective edits using advanced pattern matching.
  • Inputs:
    • path (string): File to edit.
    • edits (array): List of edit operations.
      • oldText (string): Text to search for.
      • newText (string): Text to replace with.
    • dryRun (boolean): Previews changes without applying (default: false).
  • Best Practice: Use dryRun first to preview changes.

• create_directory

  • Creates a new directory or ensures it exists.
  • Input: path (string).

• list_directory

  • Lists directory contents.
  • Input: path (string).

• move_file

  • Moves or renames files and directories.
  • Inputs:
    • source (string).
    • destination (string).

• search_files

  • Recursively searches for files/directories.
  • Inputs:
    • path (string): Starting directory.
    • pattern (string): Search pattern.
    • excludePatterns (string[]): Patterns to exclude.

• get_file_info

  • Gets detailed file/directory metadata.
  • Input: path (string).
  • Returns metadata including size, creation time, modified time, access time, type, and permissions.

• list_allowed_directories

  • Lists all directories the server can access.

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, with the ro flag for readonly access.

Docker

Note: Mount all directories to /projects.

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

To build with Docker:

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

License

This MCP server is licensed under the MIT License, allowing free use, modification, and distribution under the terms of the license. For more details, see the LICENSE file in the project repository.