FastMCP Filesystem Server 📁

A secure Python filesystem MCP (Model Context Protocol) server built with FastMCP that provides comprehensive file and directory operations for AI assistants like Claude.

Features

• 🔒 Secure Operations: Path validation and access control to prevent directory traversal attacks
• 📂 Complete File Operations: Read, write, edit, copy, and manage files
• 📁 Directory Management: Create, list, move, and manage directories
• 🔍 Advanced Search: Search files by name patterns and content with regex support
• 📊 Metadata Access: Get detailed file and directory information
• ⚡ Async Performance: Built with async/await for optimal performance
• 🛡️ Type Safety: Full type hints and validation using Pydantic

Installation

Prerequisites

• Python 3.10 or higher
• uv - Fast Python package manager

Install from Source

git clone <repository-url>
cd fastmcp_filesystem_server

# Install with uv
uv sync

# Or install in development mode
uv sync --dev

Quick Install with uv

# Install dependencies only
uv add fastmcp pydantic aiofiles

# Install with development dependencies
uv add --dev pytest pytest-asyncio black isort mypy ruff

Quick Start

Running the Server

# Basic usage - allow operations in current directory
uv run fastmcp-filesystem --allowed-dirs .

# Allow multiple directories
uv run fastmcp-filesystem --allowed-dirs /path/to/project /path/to/documents

# Custom host and port
uv run fastmcp-filesystem --allowed-dirs . --host 0.0.0.0 --port 8080

# Alternative: Run directly with Python module
uv run python -m fastmcp_filesystem.server --allowed-dirs .

Command Line Options

• --allowed-dirs: List of directories that are allowed for filesystem operations (required)
• --host: Host to bind the server to (default: localhost)
• --port: Port to bind the server to (default: 8000)
• --log-level: Logging level - DEBUG, INFO, WARNING, ERROR (default: INFO)

Available Tools

The server provides the following tools for AI assistants:

File Operations

Tool	Description
read_file	Read the complete contents of a file
read_multiple_files	Read multiple files simultaneously
write_file	Write content to a file (with overwrite control)
edit_file	Make selective edits using pattern matching or regex

Directory Operations

Tool	Description
list_directory	List directory contents with metadata
create_directory	Create directories (with parent creation)
move_file	Move or rename files and directories

Search and Metadata

Tool	Description
search_files	Search for files and directories by pattern
search_file_content	Search for text content within files
get_file_info	Get detailed metadata for files/directories
list_allowed_directories	List directories accessible to the server

Usage Examples

Basic File Operations

# Read a file
content = await read_file("/path/to/file.txt")

# Write content to a file
result = await write_file("/path/to/output.txt", "Hello, World!")

# Edit file with pattern replacement
result = await edit_file(
    "/path/to/file.py",
    search_pattern="old_function_name",
    replacement="new_function_name"
)

Directory Management

# List directory contents
contents = await list_directory("/path/to/directory", show_hidden=True)

# Create a directory
result = await create_directory("/path/to/new/directory", parents=True)

# Move a file
result = await move_file("/old/path/file.txt", "/new/path/file.txt")

Search Operations

# Search for Python files
files = await search_files(
    directory="/path/to/project",
    pattern="*.py",
    file_type="file",
    max_results=100
)

# Search for text in files
matches = await search_file_content(
    directory="/path/to/project",
    search_text="function_name",
    file_pattern="*.py",
    use_regex=False
)

# Get detailed file information
info = await get_file_info("/path/to/file.txt")

Security Features

Path Validation

• Directory Traversal Protection: Prevents ../ attacks and symlink exploitation
• Allowed Directory Enforcement: Operations restricted to pre-configured directories
• Path Normalization: Converts relative paths to absolute paths safely

Access Control

• Whitelist-based Access: Only specified directories are accessible
• Runtime Directory Updates: Allowed directories can be modified during runtime
• Permission Validation: Checks file system permissions before operations

Error Handling

• Graceful Error Responses: Detailed error messages without exposing sensitive paths
• Exception Safety: All operations wrapped in try-catch blocks
• Resource Cleanup: Automatic cleanup of file handles and temporary resources

Configuration

Environment Variables

# Optional environment variables
export FASTMCP_FS_MAX_FILE_SIZE=100MB
export FASTMCP_FS_TEMP_DIR=/tmp/fastmcp
export FASTMCP_FS_LOG_LEVEL=INFO

Programmatic Configuration

from fastmcp_filesystem.server import initialize_server

# Initialize with custom allowed directories
allowed_dirs = ["/path/to/project", "/path/to/documents"]
initialize_server(allowed_dirs)

Development

Running Tests

# Install development dependencies
uv sync --dev

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov=fastmcp_filesystem

Code Quality

# Format code
uv run black src/

# Sort imports
uv run isort src/

# Type checking
uv run mypy src/

# Linting
uv run ruff check src/

Example Usage

See examples/basic_usage.py for a comprehensive example of using the filesystem server components:

cd examples
uv run python basic_usage.py

Architecture

Component Overview

FastMCP Filesystem Server
├── Security Layer (path_validator.py)
│   ├── Path validation and normalization
│   ├── Directory traversal prevention
│   └── Access control enforcement
├── File Operations (file_ops.py)
│   ├── Read/write operations
│   ├── Pattern-based editing
│   └── Multiple file handling
├── Directory Operations (directory_ops.py)
│   ├── Directory listing and creation
│   ├── File/directory moving
│   └── Size calculation
├── Search Operations (search_ops.py)
│   ├── File and directory search
│   ├── Content-based search
│   └── Metadata extraction
└── Main Server (server.py)
    ├── FastMCP tool registration
    ├── Error handling and responses
    └── CLI interface

Design Principles

• Security First: All operations validated through security layer
• Async by Design: Non-blocking operations for better performance
• Type Safety: Comprehensive type hints and Pydantic validation
• Error Resilience: Graceful handling of all error conditions
• Extensibility: Modular design for easy feature additions

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes and add tests
4. Ensure all tests pass and code is formatted
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues, questions, or contributions, please visit the GitHub repository.

---

Built with ❤️ using FastMCP