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

Install dependencies:
```
uv sync
```
Run the development server:
```
uv run dev
```
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

Sandboxed Operations: All paths validated against root directory
Size Limits: Configurable limits prevent resource exhaustion
Depth Limits: Recursive operations bounded by max_search_depth
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:

Create a new repository at github.com/new

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

Deploy your server to Smithery at smithery.ai/new

Resources

Documentation: smithery.ai/docs
MCP Protocol: modelcontextprotocol.io
Community: Discord