vladesv/file-system-mcp-server

File System MCP Server

A secure Model Context Protocol (MCP) server that provides file management capabilities within a sandboxed environment. This server enables AI assistants to safely read, write, and manage files while maintaining strict security boundaries.

Features

Core File Operations

• Read files: Read content from text files
• Write files: Create or overwrite files with new content
• List directories: View files and folders with metadata
• Delete files: Remove files safely
• Create directories: Make new directories recursively
• File information: Get detailed metadata about files and directories

Security Features

• Sandboxed environment: All operations restricted to ./sandbox directory
• Path validation: Prevents directory traversal attacks (../, ..\\)
• Type checking: Validates file vs directory operations
• Error handling: Comprehensive error messages for debugging

Installation

1. Install dependencies:

npm install

2. Start the server:

npm start

Available Tools

read_file

Read the contents of a file (text files only).

• Parameters: path (string) - Path to the file
• Returns: File content as text or binary file notification
• Limits: 10MB max file size

write_file

Write content to a file (creates directories if needed).

• Parameters:
  • path (string) - Path to the file
  • content (string) - Content to write
• Returns: Success message with file size
• Limits: 50MB max content size

list_files

List files and directories in a directory.

• Parameters: path (string, optional) - Directory path (defaults to root)
• Returns: Formatted list with file types, sizes, and modification dates
• Limits: 1000 max files per directory

delete_file

Delete a file.

• Parameters: path (string) - Path to the file to delete
• Returns: Success message

create_directory

Create a new directory.

• Parameters: path (string) - Path to the directory to create
• Returns: Success message

file_info

Get detailed information about a file or directory.

• Parameters: path (string) - Path to examine
• Returns: Metadata including size, permissions, timestamps, and binary detection

copy_file

Copy a file to a new location.

• Parameters:
  • source (string) - Source file path
  • destination (string) - Destination file path
• Returns: Success message with file size
• Limits: 50MB max file size

move_file

Move/rename a file.

• Parameters:
  • source (string) - Source file path
  • destination (string) - Destination file path
• Returns: Success message

delete_directory

Delete a directory and all its contents recursively.

• Parameters: path (string) - Directory path to delete
• Returns: Success message

Configuration

MCP Client Setup

Option 1: Default Sandbox Mode

claude mcp add file-system "/path/to/file-system-mcp-server/src/server.js"

Option 2: Specify Working Directory

claude mcp add my-project "/path/to/file-system-mcp-server/src/server.js" "/path/to/your/project"

Option 3: Manual Configuration

{
  "mcpServers": {
    "file-system": {
      "command": "node",
      "args": ["src/server.js", "/path/to/your/project"],
      "cwd": "/path/to/file-system-mcp-server"
    }
  }
}

Working Directory Options

1. Default: Uses ./sandbox directory if no argument provided
2. Custom: Pass directory path as command line argument
3. Current Directory: Use process.cwd() by passing . as argument

Examples:

node src/server.js                           # Uses ./sandbox
node src/server.js /path/to/your/project     # Uses specified directory
node src/server.js .                         # Uses current directory

Security

Enhanced Path Validation

The server implements strict path validation to prevent:

• Directory traversal attacks (../../../etc/passwd)
• Symlink attacks using real path resolution
• Access to files outside the working directory
• Cross-drive attacks on Windows
• Invalid path formats and null bytes

File Size Limits

• Read operations: 10MB maximum file size
• Write operations: 50MB maximum content size
• Copy operations: 50MB maximum file size
• Directory listing: 1000 files maximum per directory

Binary File Protection

• Automatic detection of binary files by extension
• Content-based binary detection for unknown files
• Safe handling of binary files with appropriate messages
• Prevention of accidental binary file corruption

Comprehensive Error Handling

• Sanitized error messages that don't leak internal paths
• Proper handling of permission denied scenarios
• Disk space exhaustion protection
• File locking and busy file detection
• Cross-device move operations

Testing

Run the included security tests:

node test.js

This validates that:

• Valid paths are accepted
• Directory traversal attempts are blocked
• Security constraints work properly

File Structure

file-system-mcp-server/
├── src/                    # Source code (modular architecture)
│   ├── server.js          # Main MCP server
│   ├── config/            # Configuration files
│   │   ├── constants.js   # Server constants and limits
│   │   └── tools.js       # Tool definitions
│   ├── handlers/          # Tool handlers (business logic)
│   │   ├── file-handlers.js      # File operations
│   │   ├── directory-handlers.js # Directory operations
│   │   └── info-handlers.js      # Information operations
│   └── utils/             # Utility functions
│       ├── error-handler.js      # Error handling
│       ├── file-utils.js         # File utilities
│       └── validation.js         # Path validation
├── file-server.js         # Legacy monolithic server
├── package.json           # Node.js dependencies
├── test.js               # Security validation tests
├── test-config.json      # Example MCP client configuration
├── sandbox/              # Sandboxed working directory (auto-created)
└── README.md             # This documentation

Examples

Basic Usage

Once connected through an MCP client, you can:

1. Create a file:

   write_file("hello.txt", "Hello, World!")
   

2. Read the file:

   read_file("hello.txt")
   

3. List directory contents:

   list_files(".")
   

4. Get file information:

   file_info("hello.txt")
   

5. Create a directory:

   create_directory("my-folder")
   

6. Delete a file:

   delete_file("hello.txt")
   

Error Messages

The server provides clear error messages for common scenarios:

• "File not found: filename.txt"
• "Path is outside the allowed working directory"
• "Path is not a file: directory-name"
• "Directory not found: nonexistent-dir"

Architecture

Modular Design

The server uses a clean, modular architecture for better maintainability:

• src/server.js - Main MCP server setup and request routing
• src/config/ - Configuration management and tool definitions
• src/handlers/ - Business logic separated by functionality
• src/utils/ - Reusable utility functions and middleware

Key Features

• Separation of concerns - Each module has a single responsibility
• Standardized error handling - Consistent error responses across all tools
• Reusable utilities - Common patterns extracted into utility functions
• Easy testing - Modular design enables unit testing of individual components
• Extensible - New tools can be added easily without modifying existing code

Benefits

• Maintainability - Easier to find and fix bugs
• Testability - Individual components can be unit tested
• Extensibility - New features are easier to add
• Readability - Clear separation of concerns makes code easier to understand

Requirements

• Node.js 14+
• @modelcontextprotocol/sdk package
• MCP-compatible client (Claude Desktop, etc.)

License

MIT License