LocalFS MCP Server

A comprehensive filesystem management MCP (Model Context Protocol) server that provides sandboxed access to local filesystem operations. Built with Smithery CLI.

Features

16 Filesystem Tools

Directory Operations (5 tools)

• list_directories - List subdirectories in a path

• create_directory - Create new directories (with parent creation)

• delete_directory - Delete directories (recursive option)

• move_directory - Move or rename directories

• get_directory_metadata - Get directory statistics and info

File Operations (6 tools)

• list_files - List files in a directory

• read_file - Read file content with chunking support

• write_file - Write or overwrite files (text and binary)

• append_file - Append content to existing files

• delete_file - Delete files

• move_file - Move or rename files

• get_file_metadata - Get file stats (size, mime type, timestamps)

Search Operations (5 tools)

• search_by_name - Exact filename match

• search_by_glob - Glob pattern matching (.txt, **/.py)

• search_by_filename_regex - Regex pattern on filenames

• search_by_content_text - Plain text search in file content

• search_by_content_regex - Regex search in file content

Binary File Support

• Automatic detection of binary vs text files

• Base64 encoding for binary content

• UTF-8 text handling with error recovery

Performance & Safety

• Chunked file reads for large files (offset/limit support)

• Configurable file size limits

• Configurable search depth limits

• Lazy directory traversal with generators

Prerequisites

• Python >= 3.10

• Smithery API key: Get yours at smithery.ai/account/api-keys

Getting Started

1. Install dependencies:

   uv sync

2. Run the development server:

   uv run dev

3. Test interactively with the playground:

   uv run playground

Configuration

Each session requires a root_directory parameter and supports optional configuration:

root_directory: str         # Required - sandbox root path
max_file_size_mb: int = 100 # Optional - max file size for operations
max_search_depth: int = 10  # Optional - max recursion depth for searches

Example Connection URL

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

Usage Examples

Read a file

# Small file - read all at once
read_file(path="documents/readme.txt")

# Large file - read in chunks
read_file(path="large_file.bin", offset=0, limit=1048576)  # First 1MB

Search for files

# Find all Python files
search_by_glob(pattern="**/*.py", recursive=true)

# Find files containing "TODO"
search_by_content_text(query="TODO", path="src", recursive=true)

Directory operations

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

# List directory contents
list_files(path="projects")

Development

Project Structure

Your server code is organized in src/local_filesystem/:

• server.py - Main server setup

• core/ - Core utilities and exceptions

  • safety.py - Path validation and sandboxing

  • exceptions.py - Custom exception classes

  • constants.py - Configuration constants

• api/ - API route handlers

  • directory_routes.py - Directory operation endpoints

  • file_routes.py - File operation endpoints

  • search_routes.py - Search operation endpoints

• services/ - Business logic services

  • directory_service.py - Directory management

  • file_service.py - File management

  • search_service.py - Search capabilities

• schemas/ - Pydantic models and validation

Code Quality Tools

The project uses pre-commit hooks to maintain code quality:

• Black - Code formatting (line length: 100)

• Flake8 - Linting and style checking

• Mypy - Static type checking

Setup Pre-commit Hooks

# Install dependencies (includes pre-commit tools)
uv sync

# Install pre-commit hooks
uv run pre-commit install

# Run manually on all files
uv run pre-commit run --all-files

The hooks will automatically run on git commit to ensure code quality.

Security Features

1. Sandboxed Operations: All paths validated against root directory

2. Size Limits: Configurable limits prevent resource exhaustion

3. Depth Limits: Recursive operations bounded by max_search_depth

4. Path Traversal Protection: Prevents access outside sandbox root

Testing

Run the test suite:

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=src/local_filesystem

# Run specific test file
uv run pytest tests/integration/test_file_routes.py

Deploy

Ready to deploy? Push your code to GitHub and deploy to Smithery:

1. Create a new repository at github.com/new

2. Initialize git and push to GitHub:

   git add .
   git commit -m "LocalFS MCP server"
   git remote add origin https://github.com/YOUR_USERNAME/YOUR_REPO.git
   git push -u origin main

3. Deploy your server to Smithery at smithery.ai/new

Resources

• Documentation: smithery.ai/docs

• MCP Protocol: modelcontextprotocol.io

• Community: Discord