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:

   hljs language-bash

   Copy

   uv sync
   

2. Run the development server:

   hljs language-bash

   Copy

   uv run dev
   

3. Test interactively with the playground:

   hljs language-bash

   Copy

   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:

   hljs language-bash

   Copy

   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