file-system-mcp-server

File System MCP Server

A powerful file system management server built with FastMCP that provides a comprehensive set of tools for file and directory operations. This server allows you to perform various file system operations through a structured API, making it ideal for automation and integration with other systems.

Platform Support

The server is designed to work across different operating systems, but with varying levels of functionality:

Windows

Full feature support
Drive listing
Special folders access
Windows-specific path handling
Detailed system information

macOS/Linux

Basic file operations
Directory operations
File search and metadata
Basic system information
Note: Some Windows-specific features are not available

Future Implementation

Planned macOS Support

Native path handling for macOS
macOS-specific system information retrieval
Integration with macOS file system features
Support for macOS-specific file attributes
Implementation of macOS-specific utilities (similar to windows_utils.py)

Planned Linux Support

Native path handling for Linux
Linux-specific system information retrieval
Integration with Linux file system features
Support for Linux file permissions and attributes
Implementation of Linux-specific utilities

Cross-Platform Improvements

Unified path handling system
Platform-agnostic drive detection
Consistent system information API
Standardized file attributes across platforms
Cross-platform file system event monitoring
Universal file collection system

Timeline

Phase 1: Basic cross-platform compatibility improvements
Phase 2: Platform-specific feature implementations
Phase 3: Advanced cross-platform features
Phase 4: Performance optimizations and refinements

Features

File Operations

Copy files with backup support
Move files with backup support
Delete files with safety checks
Read file contents
Write file contents
Get file information (size, creation time, modification time)
Search files by name pattern
Create file collections for organizing related files

Directory Operations

List directory contents
Create directories
Delete directories
List directories recursively (tree-like structure)
Search directories by name pattern

System Information

Get system information (OS, CPU, memory, disk usage)
Get disk information (total space, used space, free space)
Get directory information (file count, total size)

Project Structure

file-system-mcp-server/
├── fs_server.py            # Main server implementation
├── windows_utils.py        # Windows-specific utilities (Windows only)
├── requirements.txt        # Project dependencies
└── test_prompts_example.md # Example test prompts

Collections Storage

Collections can be stored in any directory specified by the user. If no storage location is specified, collections will be stored in a default location within the project's data/collections directory.

Example usage:

# Store in default location
create_collection("my_collection", ["file1.txt", "file2.txt"])

# Store in custom location
create_collection("my_collection", ["file1.txt", "file2.txt"], storage_path="/path/to/store")

Dependencies

Required Dependencies

FastMCP
Pydantic
pywin32 (Windows only)
WMI (Windows only)

To install dependencies:

pip install -r requirements.txt

Setup

Clone the repository:

git clone https://github.com/calebmwelsh/file-system-mcp-server.git
cd file-system-mcp-server

Create and activate a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install dependencies:

pip install -r requirements.txt

Usage

For detailed MCP configuration instructions across different development environments (Claude, Cursor, Windsurf), visit: MCP Configuration Guide

Integration with Claude

To integrate the File System MCP server with Claude, add the following to your claude_desktop_config.json file:

{
  "mcpServers": {
    "file-system": {
      "command": "/absolute/path/to/python",
      "args": [
        "/absolute/path/to/file-system-mcp-server/fs_server.py"
      ]
    }
  }
}

Finding Your Python Path

To find your Python executable path, use the following command:

Windows (PowerShell):

(Get-Command python).Source

Windows (Command Prompt/Terminal):

where python

Linux/macOS (Terminal):

which python

Replace /absolute/path/to/python with the output from the appropriate command above.

Example Configuration

For Windows, your configuration might look like this:

{
  "mcpServers": {
    "file-system": {
      "command": "C:\\Users\\YourUsername\\AppData\\Local\\Programs\\Python\\Python39\\python.exe",
      "args": [
        "C:\\Users\\YourUsername\\Documents/file-system-mcp-server/fs_server.py"
      ]
    }
  }
}

For macOS/Linux:

{
  "mcpServers": {
    "file-system": {
      "command": "/usr/local/bin/python3",
      "args": [
        "/Users/YourUsername/Documents/file-system-mcp-server/fs_server.py"
      ]
    }
  }
}

After adding the configuration:

Save the claude_desktop_config.json file
Restart Claude
You can now use the file system tools by asking Claude to perform file operations

Available Tools

File Operations

copy_file: Copy a file with optional backup
move_file: Move a file with optional backup
delete_file: Delete a file with safety checks
read_file: Read file contents
write_file: Write contents to a file
get_file_info: Get detailed file information
search_files: Search files by name pattern
create_collection: Create a collection of files

Directory Operations

list_directory: List directory contents
create_directory: Create a new directory
delete_directory: Delete a directory
list_directory_recursively: Show directory structure in tree format
search_directories: Search directories by name pattern

System Information

get_system_info: Get system information
get_disk_info: Get disk usage information
get_directory_info: Get directory statistics

Known Issues

The following features are currently experiencing issues and may not work as expected:

Delete File Function
- The delete_file function may fail to properly delete files in some cases
- Users are advised to verify file deletion manually or use alternative methods when critical
- Issue is under investigation and will be fixed in a future update
List Drives Function
- The list_drives function may not correctly detect or display all available drives
- Some drives may be missing from the list or show incorrect information
- This is a known limitation and will be addressed in future updates
Platform-Specific Limitations
- Windows-specific features are not available on macOS/Linux
- Some path handling may differ between platforms
- System information retrieval varies by platform

Error Handling

The server includes comprehensive error handling for:

Invalid file paths
File/directory not found
Permission issues
Disk space limitations
Invalid operations
Platform-specific errors

Security

All file operations include path validation
Backup files are created before destructive operations
System information access is restricted to safe operations
File operations are performed with proper error handling

Contributing

Fork the repository
Create a feature branch
Commit your changes
Push to the branch
Create a Pull Request

License

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

Acknowledgments

Built with FastMCP
Uses Pydantic for data validation
Inspired by modern file system management tools

Integrations