File System MCP Server

A Model Context Protocol server that provides safe file system operations with built-in safeguards, backup mechanisms, and comprehensive error handling.

Features

• Safe file reading with metadata extraction and binary file detection

• File creation with overwrite protection and automatic directory creation

• File updates with automatic backup creation and rollback on failure

• Directory listing with filtering, pattern matching, and recursive traversal

• Safe file deletion with backup recovery (moves to backup instead of permanent deletion)

• Comprehensive error handling with structured error responses and recovery suggestions

• Security safeguards with protected path checking and file size limits

• Configurable logging with structured logging and file rotation

Installation

From Source

Dependencies

The server requires Python 3.8+ and the following packages:

• mcp - Model Context Protocol implementation

• python-magic - MIME type detection

• aiofiles - Async file operations

Quick Start

1. Create example configuration:

   file-system-mcp-server --create-example-config config.json

2. Validate configuration:

   file-system-mcp-server --validate-config --config config.json

3. Start the server:

   file-system-mcp-server --config config.json

Configuration

Configuration File

The server uses a JSON configuration file with the following options:

Configuration Options

• backup_directory: Directory where backup files are stored (default: ./.mcp_backups)

• max_file_size: Maximum file size for read operations in bytes (default: 10MB)

• max_recursion_depth: Maximum depth for recursive directory listing (default: 10)

• allowed_extensions: List of allowed file extensions, or null for all (default: null)

• protected_paths: List of paths that cannot be modified (default: system directories)

• enable_backups: Whether to create backups before destructive operations (default: true)

• log_level: Logging level - DEBUG, INFO, WARNING, ERROR, CRITICAL (default: INFO)

Kiro Integration

To use with Kiro, add the server to your MCP configuration:

Available Tools

read_file

Read file contents with metadata extraction.

Parameters:

• path (string): Path to the file to read

Features:

• Binary file detection

• Encoding detection and handling

• File metadata (size, permissions, timestamps)

• MIME type detection

write_file

Create a new file with content.

Parameters:

• path (string): Path where the file should be created

• content (string): Content to write to the file

• overwrite (boolean, optional): Whether to overwrite existing file

Features:

• Automatic directory creation

• Overwrite protection

• Backup creation for existing files

• File extension validation

update_file

Update an existing file with automatic backup.

Parameters:

• path (string): Path to the file to update

• content (string): New content for the file

Features:

• Automatic backup creation

• Rollback on failure

• File existence validation

list_directory

List directory contents with filtering options.

Parameters:

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

• pattern (string, optional): Glob pattern to filter files (e.g., *.py, test_*)

• recursive (boolean, optional): Whether to list recursively

Features:

• Pattern matching with glob syntax

• Recursive traversal with depth limits

• File metadata for each entry

• Entry counting and filtering statistics

delete_file

Safely delete a file or directory with backup.

Parameters:

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

Features:

• Moves to backup instead of permanent deletion

• Directory deletion support

• Protected path checking

• File count reporting

get_file_info

Get detailed metadata about a file or directory.

Parameters:

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

Features:

• Comprehensive metadata (size, timestamps, permissions)

• MIME type detection

• Existence checking

• Owner/group information (Unix systems)

Security Features

Protected Paths

The server prevents operations on system-critical directories:

• /etc, /usr, /bin, /sbin (Unix/Linux)

• /System (macOS)

• C:\Windows, C:\Program Files (Windows)

File Size Limits

Read operations are limited by the max_file_size configuration to prevent resource exhaustion.

Path Validation

All paths are resolved and validated to prevent directory traversal attacks.

Backup System

Destructive operations create timestamped backups before making changes, allowing for recovery.

Command Line Interface

Examples

Development

Running Tests

Code Formatting

Project Structure

Error Handling

The server provides structured error responses with:

• Error type classification (SecurityError, FileNotFound, etc.)

• Detailed error messages with context

• Recovery suggestions for common issues

• Structured logging for debugging

Example error response:

Troubleshooting

Common Issues

1. Permission Denied

   • Check file/directory permissions

   • Ensure the server has appropriate access rights

   • Verify the path is not in protected directories

2. File Too Large

   • Increase max_file_size in configuration

   • Use streaming for large files (future enhancement)

3. Backup Directory Issues

   • Ensure backup directory is writable

   • Check disk space availability

   • Verify backup directory path in configuration

4. MIME Type Detection Fails

   • Install python-magic system dependencies

   • Falls back to file extension-based detection

Logging

Enable debug logging for detailed operation information:

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests for new functionality

5. Run the test suite

6. Submit a pull request

Changelog

v0.1.0

• Initial release

• Core file operations (read, write, update, delete, list)

• Safety and backup system

• MCP server implementation

• Configuration management

• Comprehensive error handling