Filesystem

Provides MCP-based filesystem operations including read, write, edit, move, list, search, and secure boundaries.

other

1

GitHub Stars

other

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "sergiobayona-file_system_mcp": {
      "command": "ruby",
      "args": [
        "file_system_mcp.rb",
        "~/Documents",
        "~/Desktop"
      ],
      "env": {
        "FILESYSTEM_MCP_API_KEY": "your-secret-key"
      }
    }
  }
}

You run a filesystem-focused MCP server that exposes common file and directory operations over the Model Context Protocol. It lets you read, write, edit, move files, list and create directories, perform advanced searches with filters, and manage metadata, all while enforcing secure filesystem boundaries and optional API-key based authentication.

How to use

Connect to the filesystem MCP server from your MCP client to perform operations across files and directories. You can run the server locally in stdio mode, which starts a Ruby process that serves requests for the directories you specify.

Basic usage runs in standard mode without authentication, pointing to the directories you want to manage. Secure usage runs with authentication enabled, requiring an API key. In both cases your client will issue MCP calls to read, write, edit, move files, create and list directories, and search with filtering and sorting.

How to install

Prerequisites you need on your system before installing and running the server are: Ruby 3.1 or newer and Bundler.

Step by step commands to set up and run the server locally:

# Install Ruby 3.1+ and Bundler if you don’t have them
# (Use your system’s package manager to install Ruby, then install bundler)
bundle install

# Start the server in basic mode for a given root directory pair
ruby file_system_mcp.rb ~/Documents ~/Desktop

# Start the server in secure mode with an API key
FILESYSTEM_MCP_API_KEY=your-secret-key ruby file_system_mcp.rb --enable-auth ~/Documents

Configuration and security

The server enforces filesystem boundaries by only allowing access within the directories you specify when starting the process. Authentication is optional and, when enabled, requires the API key to be provided for all MCP operations.

Examples of how you can run in secure mode with an API key are shown in the usage examples above. You can also provide the API key via environment configuration when you start the server so clients can authenticate automatically.

Notes and tips

Keep the root directories aligned with your security and access controls. If you need to revoke access, rotate the API key and restart the server with the new key.

When connecting from an MCP client, you will access endpoints for reading, writing, editing, moving files; listing directories; creating directories; searching files with patterns and filters; and retrieving file/directory metadata.

Available tools

read_file

Read the complete contents of a single file.

read_multiple_files

Read multiple files in a single operation to minimize round-trips.

write_file

Create or overwrite a file with specified contents.

edit_file

Apply precise text edits with a diff preview to a file.

move_file

Move or rename files and directories within the allowed root.

list_directory

List entries in a directory with optional metadata.

create_directory

Create directories recursively within the allowed root.

search_files

Perform a basic recursive search with patterns.

find_files

Execute advanced searches with sorting, filtering, and metadata.

get_file_info

Retrieve detailed metadata for a file or directory.

get_bulk_file_info

Fetch metadata for multiple paths efficiently.