Filesystem

You run a fast, safe filesystem MCP server in Rust to perform read, write, search, and manipulation tasks on your local or networked file trees. It gives you a consistent API to access and edit files with protections around symlinks and path traversal, while offering both a local stdio interface and a remote HTTP stream interface for integration with clients and automation.

How to use

Connect to the MCP server from your client to perform common filesystem operations. You can run the server locally and interact via stdio or expose it over HTTP for remote clients. Typical workflows include reading and editing files, listing directories, performing bulk edits across multiple files, and patching binary data. Your client will send commands to read, write, search, replace, and analyze files through the MCP interface, receiving structured results and diffs.

How to install

Prerequisites you need installed on your system:

• Rust toolchain for building (rustc, cargo)

• Optional: a modern shell for running commands (bash, zsh, PowerShell)

Getting the server running locally (stdio mode)

# Build the binary in release mode for best performance
cargo build --release

# Run the server with a set of directories to manage
./target/release/filesystem-mcp-rs /projects /tmp

Getting the server running in HTTP mode

Expose the MCP server over HTTP so remote clients and cloud/CI tooling can connect. You can customize the bind address and port, and enable logging to a file.

# Local HTTP endpoint on port 8000, binding to localhost, with optional log
./target/release/filesystem-mcp-rs -s -p 8000 -b 127.0.0.1 -l server.log /projects /tmp

# Or expose on all interfaces on port 8000
./target/release/filesystem-mcp-rs -s -b 0.0.0.0 -p 8000 -l server.log /projects /tmp

Notes on usage and safety

The server enforces path canonicalization and can be configured to reject symlink escapes out of the allowed directories by default. You can opt into following a symlink that lies inside the allowlist with --allow_symlink_escape. This gives you flexibility in certain deployment scenarios, but you should understand the security implications.

Configuration and safety details

Path validation and allowlists are applied to all tools. If you need non-follow behavior for links, you can enable the opt-in setting per tool in future updates.

Troubleshooting tips

If the server fails to start, check the log file if you enabled -l, or run with -s --debug (if supported by your build) to surface more details. For HTTP mode, ensure the port is not blocked by a firewall and that the bind address is reachable from your client.

Available tools

read_text_file

Read text files with head and tail support to quickly inspect file contents.

read_media_file

Read media assets from the filesystem, returning metadata and content as needed.

read_multiple_files

Fetch multiple files in a single operation for batch processing.

write_file

Write or overwrite a file with new content.

edit_file

Apply diffs to a file, with an optional dry-run to preview changes.

edit_lines

Line-based edits by line numbers, including insert, replace, and delete with unified diff output.

bulk_edits

Mass search/replace across many files using glob patterns and optional regex with capture groups.

extract_lines

Cut out lines by number ranges and optionally return the extracted content.

extract_symbols

Cut characters by Unicode positions to extract or remove text blocks.

read_binary

Read bytes from a binary file and return base64-encoded data.

write_binary

Write bytes to a binary file with options to replace or insert data.

extract_binary

Remove a byte range from a binary file and return base64-encoded data.

patch_binary

Find and replace binary patterns using base64-encoded data.

create_directory

Create new directories within the allowed path scope.

move_file

Move files or directories, preserving structure and applying safety checks.

copy_file

Copy files or directories with overwrite protection when needed.

delete_path

Recursively delete a path and its contents within allowed directories.

list_directory

List entries in a directory with optional details.

list_directory_with_sizes

List directory contents including file sizes.

get_file_info

Retrieve metadata about a specific file.

directory_tree

Return a hierarchical representation of a directory structure.

search_files

Glob-based search with excludes to locate files by path patterns.

grep_files

Regex-based content search inside files with optional context lines.

list_allowed_directories

Show directories that are allowed by the current policy.