Filesystem MCP Server (v0.1)
A simple MCP server for filesystem operations with directory sandboxing and read-only mode support.
Early version (0.1) - not thoroughly tested/reviewed, use with caution
Quick Start
Install dependencies:
git clone <repo_url>
uv sync
Run the server:
# Normal mode - full filesystem access
uv run main.py /path/to/allowed/directory
# Read-only mode - no write operations
uv run main.py --read-only /path/to/allowed/directory
Features
- Directory sandboxing (operations restricted to allowed paths)
--read-onlyflag disables write operations- Gitignore support for searches
- Human-readable error messages
Usage Examples
Normal Mode
uv run main.py ~/projects
# Provides: create_file, delete_file, move_file, edit_file, create_directory + read tools
Read-Only Mode
uv run main.py --read-only ~/projects
# Provides only: read_text_file, list_directory, search_files, grep, directory_tree
Multiple Directories
uv run main.py /home/user/docs /tmp/workspace
uv run main.py --read-only /var/log /etc/config
Available Tools
Read Operations (always available):
read_text_file- Read file contentslist_directory- List directory contentsdirectory_tree- JSON directory structuresearch_files- Find files by patterngrep- Search text in filesread_multiple_files- Bulk file reading
Write Operations (disabled in --read-only):
create_file- Create new filesdelete_file- Delete filesmove_file- Move/rename filesedit_file- Edit file contentscreate_directory- Create directories
Dependencies
From pyproject.toml:
fastmcp>=2.11.2- MCP frameworkpathspec>=0.12.1- Gitignore patterns
Security Notes
- All paths resolved with
Path.resolve()to prevent traversal - Operations restricted to allowed directories only
- Binary files rejected for text operations