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:

Example Connection URL

Usage Examples

Read a file

Search for files

Directory operations

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

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:

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