File System

You can run a File System MCP Server to perform safe, auditable file system operations via the Model Context Protocol. It provides read, write, update, delete, and list capabilities with built-in backups, error handling, and security safeguards so you can manage files and directories through MCP clients confidently and safely.

How to use

To use the File System MCP Server, run the local server process and connect to it from an MCP client. You will typically start the server with a configuration file that defines backup behavior, size limits, protected paths, and logging. Your client can then perform operations such as reading files, writing new content, updating existing files, listing directory contents, and safely deleting files with backups.

How to install

Prerequisites you need before installation are Python 3.8 or newer and a working command line environment.

# Clone the server 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]"

Configuration and usage notes

You configure the server with a JSON file that controls backup behavior, file size limits, recursion depth for listings, and protected paths. The default example includes a backup directory, max file size, and protected system paths.

{
  "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"
}

Starting with example configuration

Create an example configuration file, validate it, then start the server using that configuration.

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

Available tools

read_file

Read file contents with metadata extraction, including MIME type detection, encoding handling, and binary detection.

write_file

Create a new file with content, automatically creating required directories, with overwrite protection and backup creation for existing files.

update_file

Update an existing file with automatic backup, including rollback on failure and validation that the target exists.

list_directory

List directory contents with optional pattern filtering and recursive traversal, including per-entry metadata.

delete_file

Safely delete a file or directory by moving it to a backup location, with protected path checks and optional directory support.

get_file_info

Return comprehensive metadata for a file or directory, including size, timestamps, permissions, and MIME type.