fs

This Filesystem MCP Server exposes a set of MCP tools to interact with the local filesystem in a controlled and secure manner. Supported tools include listing directories (list), reading file contents (read), writing files (write), creating directories (mkdir), deleting items (delete), copying (copy) and moving (move) files or directories, retrieving detailed file information (info), searching file contents (search), listing all configured allowed directories (list_allowed_dirs), and performing partial edits on files (edit). All operations are restricted to configured allowed directories and validated to prevent directory traversal or access outside the permitted scope. Clients connect via the MCP protocol over a standard transport (as shown in the client example) and issue tool calls with the appropriate parameters. The server emphasizes absolute paths and security checks to ensure operations stay within the defined root directories.

Prerequisites:

• Rust toolchain (1.70.0 or later) and Cargo
• Build environment with a compatible Rust target

1. Install Rust and Cargo if you don't have them:

   • On Unix-like systems: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh source $HOME/.cargo/env

2. Clone the repository (or obtain the code for the FS MCP server):

   git clone https://github.com/colinrozzi-fs-mcp-server.git cd colinrozzi-fs-mcp-server

3. Build the server in release mode:

   cargo build --release

4. Run the server (example without explicit allowed dirs):

   ./target/release/fs-mcp-server

5. (Optional) Run with explicit allowed directories and other settings:

   ./target/release/fs-mcp-server --allowed-dirs /path/to/dir1,/path/to/dir2 ./target/release/fs-mcp-server --config-file /path/to/config.txt FS_ALLOWED_DIRS=/data,/home/user/docs FS_LOG_LEVEL=debug ./target/release/fs-mcp-server

6. Verify the server is running by connecting with an MCP client and invoking tools like list_allowed_dirs, then perform basic operations ensuring paths are absolute and within the configured allowed directories.

Tips and common considerations:

• Always provide absolute paths for the path parameter. The server enforces access only within configured allowed directories.
• Use a configuration file to persistently define allowed directories for easier management.
• Set FS_MAX_FILE_SIZE to control read operations and guard against large payloads.
• Adjust FS_LOG_LEVEL to control the verbosity of logs; for troubleshooting, use debug or trace.
• If encountering permission or traversal errors, double-check the provided paths against the allowed directories and ensure proper ownership/permissions at the OS level.
• When using partial edits via edit, backup is strongly recommended to prevent data loss in case of errors.