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.jsonfile - 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 backupmove_file: Move a file with optional backupdelete_file: Delete a file with safety checksread_file: Read file contentswrite_file: Write contents to a fileget_file_info: Get detailed file informationsearch_files: Search files by name patterncreate_collection: Create a collection of files
Directory Operations
list_directory: List directory contentscreate_directory: Create a new directorydelete_directory: Delete a directorylist_directory_recursively: Show directory structure in tree formatsearch_directories: Search directories by name pattern
System Information
get_system_info: Get system informationget_disk_info: Get disk usage informationget_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_filefunction 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
- The
-
List Drives Function
- The
list_drivesfunction 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
- The
-
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