📁 Filesystem MCP Server

A comprehensive Model Context Protocol (MCP) server that provides secure filesystem operations with directory allowlisting, robust error handling, and comprehensive file management capabilities.

✨ Features

• 🔒 Security First - Directory allowlisting prevents unauthorized access
• 📖 Comprehensive File Reading - Text files, media files, and batch operations
• ✏️ Advanced File Editing - Line-based edits with git-style diff output
• 📁 Directory Management - Create, list, and navigate directory structures
• 🔍 Powerful Search - Pattern-based file search with exclusion filters
• 🌳 Tree Views - Recursive directory tree visualization as JSON
• 📊 File Information - Detailed metadata including size, permissions, and timestamps
• 🚚 File Operations - Move, rename, and organize files safely
• 🛡️ Robust Error Handling - Comprehensive error messages with context
• 🧹 Input Validation - Automatic path validation and sanitization
• 📚 Rich Documentation - Built-in help and operation guidance
• 🎯 SOLID Architecture - Clean, maintainable, and testable codebase

🚀 Installation & Usage

Install from Crates.io

cargo install mcp-server-filesystem

Run the Server

# Start the MCP server with allowed directories (communicates via stdio)
mcp-server-filesystem /path/to/allowed/directory

# Allow multiple directories
mcp-server-filesystem /home/user/projects /tmp/workspace

# Enable debug logging
mcp-server-filesystem /path/to/dir --log-level debug

Test with MCP Inspector

# Install and run the MCP Inspector to test the server
npx @modelcontextprotocol/inspector mcp-server-filesystem /path/to/test/dir

Use with Claude Desktop

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "filesystem": {
      "command": "mcp-server-filesystem",
      "args": ["."]
    }
  }
}

🛠️ Available Tools

File Reading Operations

read_text_file

Read the complete contents of a text file with optional head/tail functionality.

Parameters:

• path (string): Path to the file to read
• head (optional number): Read only the first N lines
• tail (optional number): Read only the last N lines

Example Request:

{
  "path": "/home/user/projects/README.md",
  "head": 10
}

Example Response:

{
  "content": "# My Project\n\nThis is a sample project...",
  "path": "/home/user/projects/README.md",
  "size": 1024,
  "encoding": "utf-8"
}

read_media_file

Read image or audio files and return base64 encoded data with MIME type detection.

Parameters:

• path (string): Path to the media file

Example Request:

{
  "path": "/home/user/images/photo.jpg"
}

Example Response:

{
  "content": "/9j/4AAQSkZJRgABAQEAYABgAAD...",
  "mime_type": "image/jpeg",
  "path": "/home/user/images/photo.jpg",
  "size": 245760
}

read_multiple_files

Read multiple files simultaneously for efficient batch operations.

Parameters:

• paths (array of strings): Array of file paths to read

Example Request:

{
  "paths": [
    "/home/user/config.json",
    "/home/user/settings.yaml",
    "/home/user/data.txt"
  ]
}

File Writing Operations

write_file

Create a new file or completely overwrite an existing file with new content.

Parameters:

• path (string): Path where the file should be written
• content (string): Content to write to the file

Example Request:

{
  "path": "/home/user/projects/new_file.txt",
  "content": "Hello, World!\nThis is a new file."
}

edit_file

Make line-based edits to a text file with git-style diff output.

Parameters:

• path (string): Path to the file to edit
• edits (array): Array of edit operations
• dry_run (optional boolean): Preview changes without applying them

Edit Operation Format:

{
  "old_text": "original line content",
  "new_text": "new line content"
}

Example Request:

{
  "path": "/home/user/config.py",
  "edits": [
    {
      "old_text": "DEBUG = False",
      "new_text": "DEBUG = True"
    }
  ],
  "dry_run": false
}

Directory Operations

create_directory

Create a new directory or ensure a directory exists, including parent directories.

Parameters:

• path (string): Path of the directory to create

Example Request:

{
  "path": "/home/user/projects/new_project/src"
}

list_directory

Get a detailed listing of all files and directories in a specified path.

Parameters:

• path (string): Path to the directory to list

Example Response:

{
  "entries": [
    {
      "name": "README.md",
      "type": "[FILE]",
      "size": 1024
    },
    {
      "name": "src",
      "type": "[DIRECTORY]",
      "size": 0
    }
  ],
  "path": "/home/user/projects",
  "total_entries": 2
}

list_directory_with_sizes

Get a detailed listing with file sizes and sorting options.

Parameters:

• path (string): Path to the directory to list
• sort_by (string): Sort criteria ("name", "size", "modified")

directory_tree

Get a recursive tree view of files and directories as JSON.

Parameters:

• path (string): Root path for the tree
• exclude_patterns (optional array): Glob patterns to exclude

Example Request:

{
  "path": "/home/user/projects",
  "exclude_patterns": ["*.log", "node_modules/**", ".git/**"]
}

File Management Operations

move_file

Move or rename files and directories safely.

Parameters:

• source (string): Source path
• destination (string): Destination path

Example Request:

{
  "source": "/home/user/old_name.txt",
  "destination": "/home/user/documents/new_name.txt"
}

search_files

Search for files and directories matching a pattern with exclusion support.

Parameters:

• path (string): Directory to search in
• pattern (string): Glob pattern to match
• exclude_patterns (optional array): Patterns to exclude

Example Request:

{
  "path": "/home/user/projects",
  "pattern": "*.rs",
  "exclude_patterns": ["target/**", "*.tmp"]
}

get_file_info

Retrieve detailed metadata about a file or directory.

Parameters:

• path (string): Path to the file or directory

Example Response:

{
  "name": "config.json",
  "type": "[FILE]",
  "size": 2048,
  "is_directory": false,
  "modified": 1642694400,
  "path": "/home/user/config.json",
  "permissions": {
    "readable": true,
    "writable": true,
    "executable": false
  }
}

Utility Operations

list_allowed_directories

Returns the list of directories that this server is allowed to access.

Example Response:

Allowed directories:
/home/user/projects
/home/user/documents
/tmp/workspace

📚 Available Resources

The server provides built-in resources for help and status information:

fs://status

Current server status, configuration, and capabilities information.

Example Content:

Filesystem MCP Server Status

Server: Running
Allowed Directories: /home/user/projects, /home/user/documents
Total Allowed Paths: 2
Tools Available: 13
Resources Available: 3

Capabilities:
- Secure file reading (text and media files)
- File writing and editing with line-based operations
- Directory management and navigation
- File search with pattern matching and exclusions
- File metadata and information retrieval
- File operations (move, rename, copy)
- Directory tree visualization
- Security through directory allowlisting

fs://help

Comprehensive help documentation with tool descriptions, examples, and usage patterns.

Content includes:

• Complete tool reference with parameters and examples
• Security model explanation
• Pattern syntax guide
• Example workflows for common tasks
• Allowed directories listing

fs://allowed-directories

Detailed information about configured allowed directories and security model.

Example Content:

Allowed Directories Configuration

The Filesystem MCP Server is configured with the following allowed directories.
All file operations are restricted to these paths and their subdirectories.

ALLOWED PATHS:
  1. /home/user/projects
  2. /home/user/documents

SECURITY INFORMATION:
- All file paths are validated against these allowed directories
- Operations outside these paths will be rejected
- Symlinks pointing outside allowed directories trigger warnings
- Path traversal attempts (../) are blocked

🔧 Configuration

Command Line Options

mcp-server-filesystem [OPTIONS]

Options:
  -a, <PATH>    Add an allowed directory (can be used multiple times)
  -l, --log-level <LEVEL>     Set logging level [default: info] [possible values: trace, debug, info, warn, error]
  -f, --log-format <FORMAT>   Set log format [default: pretty] [possible values: pretty, json, compact]
      --help                  Print help information
      --version               Print version information

Security Model

The server implements a strict security model:

• Directory Allowlisting: Only specified directories can be accessed
• Path Validation: All paths are validated and normalized
• Symlink Protection: Symlinks are handled safely with warnings
• Size Limits: Configurable file size limits prevent abuse
• Error Sanitization: Error messages don't leak sensitive information

📖 Usage Examples

With Claude Desktop

Once configured, you can ask Claude:

"Read the contents of my project's README.md file"

"Create a new directory structure for a Python project"

"Search for all Python files in my project and show their contents"

"Edit my configuration file to enable debug mode"

"Show me a tree view of my project directory, excluding build artifacts"

"Show me the server status and available resources"

With MCP Inspector

# Test the server interactively
npx @modelcontextprotocol/inspector mcp-server-filesystem /path/to/test

# Try these operations:
# 1. Use read_text_file to examine files
# 2. Use directory_tree to explore structure
# 3. Use search_files to find specific files
# 4. Use edit_file to make changes with dry_run: true
# 5. Browse resources: fs://status, fs://help, fs://allowed-directories

Command Line Testing

# Use MCP Inspector for interactive testing
npx @modelcontextprotocol/inspector mcp-server-filesystem /home/user/projects

# Test specific operations:
# - File reading: read_text_file, read_multiple_files
# - Directory operations: list_directory, directory_tree
# - File management: write_file, edit_file, move_file
# - Search: search_files with various patterns
# - Resources: Browse fs://status, fs://help, fs://allowed-directories

🚨 Error Handling

The server provides detailed error messages for common issues:

• Path Not Found: Clear indication when files or directories don't exist
• Permission Denied: Helpful messages for access issues
• Invalid Patterns: Guidance for correct glob pattern syntax
• Validation Errors: Specific feedback on parameter validation failures
• Security Violations: Safe error messages for unauthorized access attempts

🧪 Testing

Run the comprehensive test suite:

# Run all tests
cargo test

# Run specific test categories
cargo test read_files
cargo test search_files
cargo test get_file_info

# Run with coverage
cargo tarpaulin --out html

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

1. Clone the repository
2. Install Rust (1.70+ required)
3. Run cargo build
4. Run cargo test

Code Style

This project follows SOLID principles and Domain-Driven Design:

• Clean Architecture: Separation of concerns with clear layers
• Dependency Injection: Testable and maintainable code
• Comprehensive Testing: Unit and integration tests
• Error Handling: Robust error types and handling

Run cargo fmt and cargo clippy before submitting.

📄 License

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

🙏 Acknowledgments

• Built with rmcp - Rust MCP implementation
• File operations powered by tokio
• Pattern matching via globset
• MIME type detection using mime_guess

📞 Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

---