File Operations MCP Server
local-only server
The server can only run on the client’s local machine because it depends on local resources.
File Operations MCP Server
A Model Context Protocol (MCP) server that provides enhanced file operation capabilities with streaming, patching, and change tracking support.
Features
- Basic File Operations: Copy, read, write, move, and delete files
- Directory Operations: Create, remove, and copy directories
- File Watching: Monitor files and directories for changes
- Change Tracking: Track and query file operation history
- Streaming Support: Handle large files efficiently with streaming
- Resource Support: Access files and directories through MCP resources
- Progress Reporting: Real-time progress updates for long operations
- Rate Limiting: Protection against excessive requests
- Enhanced Security: Path validation and input sanitization
- Robust Error Handling: Comprehensive error handling and reporting
- Type Safety: Full TypeScript support with strict type checking
Installation
Installing via Smithery
To install File Operations Server for Claude Desktop automatically via Smithery:
Manual Installation
Usage
Starting the Server
For development with auto-reloading:
Available Tools
Basic File Operations
copy_file
: Copy a file to a new locationread_file
: Read content from a filewrite_file
: Write content to a filemove_file
: Move/rename a filedelete_file
: Delete a fileappend_file
: Append content to a file
Directory Operations
make_directory
: Create a directoryremove_directory
: Remove a directorycopy_directory
: Copy a directory recursively (with progress reporting)
Watch Operations
watch_directory
: Start watching a directory for changesunwatch_directory
: Stop watching a directory
Change Tracking
get_changes
: Get the list of recorded changesclear_changes
: Clear all recorded changes
Available Resources
Static Resources
file:///recent-changes
: List of recent file system changes
Resource Templates
file://{path}
: Access file contentsmetadata://{path}
: Access file metadatadirectory://{path}
: List directory contents
Example Usage
Rate Limits
The server implements rate limiting to prevent abuse:
- Tools: 100 requests per minute
- Resources: 200 requests per minute
- Watch Operations: 20 operations per minute
Rate limit errors include a retry-after period in the error message.
Security Features
Path Validation
All file paths are validated to prevent directory traversal attacks:
- No parent directory references (
../
) - Proper path normalization
- Input sanitization
Resource Protection
- Rate limiting on all operations
- Proper error handling and logging
- Input validation on all parameters
- Safe resource cleanup
Progress Reporting
Long-running operations like directory copying provide progress updates:
Progress can be tracked through the progress token returned in the operation result.
Development
Building
Linting
Formatting
Testing
Configuration
The server can be configured through various settings:
- Rate Limiting: Configure request limits and windows
- Progress Reporting: Control update frequency and detail level
- Resource Access: Configure resource permissions and limits
- Security Settings: Configure path validation rules
- Change Tracking: Set retention periods and storage options
- Watch Settings: Configure debounce times and recursive watching
Error Handling
The server provides detailed error information through the FileOperationError
class and MCP error codes:
Standard MCP Error Codes
InvalidRequest
: Invalid parameters or request formatMethodNotFound
: Unknown tool or resource requestedInvalidParams
: Invalid parameters (e.g., path validation failure)InternalError
: Server-side errors
Custom Error Types
- File operation failures
- Rate limit exceeded
- Path validation errors
- Resource access errors
Each error includes:
- Specific error code
- Detailed error message
- Relevant metadata (file paths, limits, etc.)
- Stack traces in development mode
Contributing
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature
) - Commit your changes (
git commit -m 'Add amazing feature'
) - Push to the branch (
git push origin feature/amazing-feature
) - Open a Pull Request
License
This project is licensed under the MIT License - see the LICENSE file for details.
You must be authenticated.
A Model Context Protocol server that enables enhanced file system operations including reading, writing, copying, moving files with streaming capabilities, directory management, file watching, and change tracking.
- Features
- Installation
- Usage
- Rate Limits
- Security Features
- Progress Reporting
- Development
- Configuration
- Error Handling
- Contributing
- License