LocalFS

You are provisioning an MCP server that provides sandboxed filesystem operations. This LocalFS MCP Server lets you manage directories and files, search content, and work with binary or text data safely through a structured API, while enforcing configurable limits and sandbox boundaries.

How to use

Connect to the MCP server using an HTTP URL or run a local process that exposes the same capabilities. You can perform operations such as listing, reading, writing, moving, and deleting files and directories, as well as performing targeted searches by name, glob patterns, filename regex, and content.

Typical operations you will perform include reading a small file in one go, streaming a large file in chunks, creating nested directories, listing directory contents, and running searches across your sandbox. When reading large files, leverage chunked reads with offset and limit to avoid loading the entire file into memory.

How to install

Prerequisites you need before starting: Python 3.10 or newer.

Install the required tooling and dependencies using the Smithery CLI. Run the following commands to install dependencies, start the development server, and open the interactive playground.

uv sync
uv run dev
uv run playground

Configuration

Each session requires a sandbox root directory. You can optionally configure limits for file sizes and search depth to control resource usage and traversal.

root_directory: "/path/to/sandbox"         # Required - sandbox root path
max_file_size_mb: 100                      # Optional - max file size for operations
max_search_depth: 10                       # Optional - max recursion depth for searches

Security and safety notes

All filesystem operations are sandboxed to the configured root directory. Paths are validated to prevent traversal outside the sandbox, and file operations respect configurable size limits and depth limits to prevent resource exhaustion.

Usage examples

Read a small file in one go: read_file(path="documents/readme.txt")

Read a large file in chunks: read_file(path="large_file.bin", offset=0, limit=1048576) # First 1MB

Create nested directories: create_directory(path="projects/new_project", create_parents=true)

List contents of a directory: list_files(path="projects")

Find Python files using a glob: search_by_glob(pattern="**/*.py", recursive=true)

Search for files containing a text string: search_by_content_text(query="TODO", path="src", recursive=true)

Available tools and capabilities

The server exposes a broad set of filesystem tools for practical tasks across directories and files, plus search capabilities to locate resources by name, pattern, or content.

Example connection URL

Use the HTTP connection URL to connect to the MCP server with the sandbox root and optional limits.

http://localhost:8081/mcp?root_directory=/path/to/sandbox&max_file_size_mb=100

Available tools

list_directories

List subdirectories within a given path to understand directory structure and availability.

create_directory

Create a new directory, with support for creating parent directories as needed.

delete_directory

Delete a directory, with an option for recursive removal.

move_directory

Move or rename a directory, preserving contents when possible.

get_directory_metadata

Retrieve statistics and information about a directory, such as size, timestamps, and permissions.

list_files

List files contained in a directory.

read_file

Read file content with support for chunked reads to handle large files efficiently.

write_file

Write or overwrite a file, handling both text and binary data.

append_file

Append data to an existing file without overwriting existing content.

delete_file

Remove a file from the filesystem.

move_file

Move or rename a file within the sandbox.

get_file_metadata

Get metadata for a file, including size, mime type, and timestamps.

search_by_name

Find files or directories by exact filename match.

search_by_glob

Search using glob patterns (for example, *.txt or **/*.py) to match paths.

search_by_filename_regex

Search by regular expression applied to filenames.

search_by_content_text

Search file contents for plain text matches.

search_by_content_regex

Search file contents using regular expressions.