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

# Clone the repository
git clone <repository-url>
cd file-system-mcp-server

# Install in development mode
pip install -e .

# Or install with development dependencies
pip install -e ".[dev]"

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

Create example configuration:

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

Validate configuration:

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

Start the server:

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

Configuration

Configuration File

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

{
  "backup_directory": "./.mcp_backups",
  "max_file_size": 10485760,
  "max_recursion_depth": 10,
  "allowed_extensions": null,
  "protected_paths": ["/etc", "/usr", "/bin", "/System"],
  "enable_backups": true,
  "log_level": "INFO"
}

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:

{
  "mcpServers": {
    "file-system-operations": {
      "command": "file-system-mcp-server",
      "args": ["--config", "config.json"],
      "disabled": false,
      "autoApprove": ["read_file", "get_file_info", "list_directory"]
    }
  }
}

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

file-system-mcp-server [OPTIONS]

Options:
  -c, --config PATH           Path to configuration file
  --log-level LEVEL          Set logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
  --log-file PATH            Path to log file
  --validate-config          Validate configuration and exit
  --create-example-config PATH  Create example configuration file and exit
  --version                  Show version and exit
  --help                     Show help message

Examples

# Run with default configuration
file-system-mcp-server

# Run with custom config and debug logging
file-system-mcp-server --config my-config.json --log-level DEBUG

# Log to file
file-system-mcp-server --log-file server.log

# Create example configuration
file-system-mcp-server --create-example-config my-config.json

# Validate configuration
file-system-mcp-server --validate-config --config my-config.json

Development

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Run specific test file
pytest tests/unit/test_config.py

Code Formatting

# Format code
black src tests

# Sort imports
isort src tests

# Type checking
mypy src

Project Structure

file-system-mcp-server/
├── src/file_system_mcp_server/
│   ├── __init__.py
│   ├── main.py              # CLI entry point
│   ├── server.py            # MCP server implementation
│   ├── config.py            # Configuration management
│   ├── safety.py            # Security and backup management
│   ├── file_operations.py   # Core file operations
│   ├── models.py            # Data models and result types
│   └── logging_config.py    # Logging configuration
├── tests/
│   ├── unit/                # Unit tests
│   ├── integration/         # Integration tests
│   └── fixtures/            # Test fixtures
├── config/
│   ├── example.json         # Example configuration
│   └── kiro-mcp.json        # Kiro MCP configuration
├── pyproject.toml           # Project configuration
└── README.md

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:

{
  "success": false,
  "error": {
    "error_type": "FileNotFound",
    "message": "File does not exist: /path/to/file.txt",
    "recovery_suggestions": [
      "Check the file path",
      "Ensure the file exists"
    ]
  }
}

Troubleshooting

Common Issues

Permission Denied
- Check file/directory permissions
- Ensure the server has appropriate access rights
- Verify the path is not in protected directories
File Too Large
- Increase max_file_size in configuration
- Use streaming for large files (future enhancement)
Backup Directory Issues
- Ensure backup directory is writable
- Check disk space availability
- Verify backup directory path in configuration
MIME Type Detection Fails
- Install python-magic system dependencies
- Falls back to file extension-based detection

Logging

Enable debug logging for detailed operation information:

file-system-mcp-server --log-level DEBUG --log-file debug.log

License

MIT License - see LICENSE file for details.

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Run the test suite
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

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

# Clone the repository
git clone <repository-url>
cd file-system-mcp-server

# Install in development mode
pip install -e .

# Or install with development dependencies
pip install -e ".[dev]"

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

Create example configuration:

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

Validate configuration:

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

Start the server:

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

Configuration

Configuration File

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

{
  "backup_directory": "./.mcp_backups",
  "max_file_size": 10485760,
  "max_recursion_depth": 10,
  "allowed_extensions": null,
  "protected_paths": ["/etc", "/usr", "/bin", "/System"],
  "enable_backups": true,
  "log_level": "INFO"
}

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:

{
  "mcpServers": {
    "file-system-operations": {
      "command": "file-system-mcp-server",
      "args": ["--config", "config.json"],
      "disabled": false,
      "autoApprove": ["read_file", "get_file_info", "list_directory"]
    }
  }
}

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

file-system-mcp-server [OPTIONS]

Options:
  -c, --config PATH           Path to configuration file
  --log-level LEVEL          Set logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
  --log-file PATH            Path to log file
  --validate-config          Validate configuration and exit
  --create-example-config PATH  Create example configuration file and exit
  --version                  Show version and exit
  --help                     Show help message

Examples

# Run with default configuration
file-system-mcp-server

# Run with custom config and debug logging
file-system-mcp-server --config my-config.json --log-level DEBUG

# Log to file
file-system-mcp-server --log-file server.log

# Create example configuration
file-system-mcp-server --create-example-config my-config.json

# Validate configuration
file-system-mcp-server --validate-config --config my-config.json

Development

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Run specific test file
pytest tests/unit/test_config.py

Code Formatting

# Format code
black src tests

# Sort imports
isort src tests

# Type checking
mypy src

Project Structure

file-system-mcp-server/
├── src/file_system_mcp_server/
│   ├── __init__.py
│   ├── main.py              # CLI entry point
│   ├── server.py            # MCP server implementation
│   ├── config.py            # Configuration management
│   ├── safety.py            # Security and backup management
│   ├── file_operations.py   # Core file operations
│   ├── models.py            # Data models and result types
│   └── logging_config.py    # Logging configuration
├── tests/
│   ├── unit/                # Unit tests
│   ├── integration/         # Integration tests
│   └── fixtures/            # Test fixtures
├── config/
│   ├── example.json         # Example configuration
│   └── kiro-mcp.json        # Kiro MCP configuration
├── pyproject.toml           # Project configuration
└── README.md

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:

{
  "success": false,
  "error": {
    "error_type": "FileNotFound",
    "message": "File does not exist: /path/to/file.txt",
    "recovery_suggestions": [
      "Check the file path",
      "Ensure the file exists"
    ]
  }
}

Troubleshooting

Common Issues

Permission Denied
- Check file/directory permissions
- Ensure the server has appropriate access rights
- Verify the path is not in protected directories
File Too Large
- Increase max_file_size in configuration
- Use streaming for large files (future enhancement)
Backup Directory Issues
- Ensure backup directory is writable
- Check disk space availability
- Verify backup directory path in configuration
MIME Type Detection Fails
- Install python-magic system dependencies
- Falls back to file extension-based detection

Logging

Enable debug logging for detailed operation information:

file-system-mcp-server --log-level DEBUG --log-file debug.log

License

MIT License - see LICENSE file for details.

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Run the test suite
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