Filesystem MCP Server

A comprehensive, secure, cross-platform MCP (Model Context Protocol) server for advanced file system operations with enterprise-grade security features.

Features

🔒 Security & Access Control

• Path Validation: Prevents directory traversal attacks
• Sandboxing: Configurable path restrictions
• Rate Limiting: Prevents abuse with configurable limits
• Audit Logging: Comprehensive operation tracking
• Permission Validation: File system permission checks

📁 File Operations

• Basic Operations: Read, write, delete, copy, move files
• Directory Operations: Create, list, delete directories
• Batch Operations: Efficient bulk file operations
• File Information: Detailed metadata and statistics
• Search: Advanced file search with filters

🗜️ Compression & Archives

• ZIP Support: Create and extract ZIP archives
• GZIP Support: Single file compression
• Archive Listing: View archive contents
• Nested Archives: Handle complex archive structures

👁️ File Watching

• Real-time Monitoring: Watch files and directories for changes
• Event Filtering: Configurable event types
• Cross-platform: Works on Windows, macOS, and Linux

🌐 Cross-Platform Compatibility

• Windows: Full support including long paths
• macOS: Native file system features
• Linux: POSIX compliance
• Path Handling: Automatic path normalization

Installation

npm install filesystem-mcp-server

Quick Start

Basic Usage

import { FileSystemMCPServer } from 'filesystem-mcp-server';

const server = new FileSystemMCPServer({
  allowedPaths: ['/safe/directory'],
  restrictedPaths: ['/system', '/etc'],
  rateLimit: {
    enabled: true,
    maxRequests: 100,
    windowMs: 60000
  }
});

await server.start();

Available Tools

File Operations

1. read_file

   • Description: Read the contents of a file
   • Parameters:
     • filePath (string): Path to the file to read
     • encoding (optional): Text encoding (utf8, ascii, base64, hex, binary, utf16le)

2. write_file

   • Description: Write content to a file
   • Parameters:
     • filePath (string): Path to the file to write
     • content (string): Content to write
     • encoding (optional): Text encoding
     • createDirectories (optional boolean): Create parent directories if needed

3. delete_file

   • Description: Delete a file
   • Parameters:
     • filePath (string): Path to the file to delete

4. copy_file

   • Description: Copy a file from source to destination
   • Parameters:
     • sourcePath (string): Source file path
     • destinationPath (string): Destination file path
     • overwrite (optional boolean): Whether to overwrite existing files

5. move_file

   • Description: Move or rename a file
   • Parameters:
     • sourcePath (string): Source file path
     • destinationPath (string): Destination file path

6. get_file_info

   • Description: Get detailed information about a file or directory
   • Parameters:
     • path (string): Path to the file or directory

7. file_exists

   • Description: Check if a file or directory exists
   • Parameters:
     • path (string): Path to check

Directory Operations

8. list_directory

   • Description: List the contents of a directory
   • Parameters:
     • dirPath (string): Path to the directory
     • includeHidden (optional boolean): Include hidden files

9. create_directory

   • Description: Create a new directory
   • Parameters:
     • dirPath (string): Path to create
     • recursive (optional boolean): Create parent directories

10. delete_directory

    • Description: Delete a directory
    • Parameters:
      • dirPath (string): Path to delete
      • recursive (optional boolean): Delete recursively

Available Resources

File Resources

Access file contents using file:// URIs:

file:///path/to/your/file.txt

Directory Resources

Access directory listings using directory:// URIs:

directory:///path/to/your/directory

Security Features

• Path Validation: All paths are validated and normalized to prevent directory traversal attacks
• Permission Checking: File and directory permissions are checked before operations
• Error Handling: Comprehensive error handling with descriptive messages
• Cross-Platform Support: Works on both Windows and Linux with proper path handling

Configuration

The server runs with stdio transport by default. For custom configurations or different transports, modify the src/index.ts file.

Development

Project Structure

src/
├── index.ts                    # Main server entry point
├── tools/
│   └── fileSystemTools.ts      # File system tool implementations
├── resources/
│   └── fileSystemResources.ts  # File system resource implementations
└── utils/
    ├── fileOperations.ts       # Core file system operations
    └── pathUtils.ts            # Path validation and utilities

Building

npm run build

Development Mode

npm run dev

Cleaning Build Files

npm run clean

Examples

Reading a File

{
  "name": "read_file",
  "arguments": {
    "filePath": "/path/to/file.txt",
    "encoding": "utf8"
  }
}

Writing a File

{
  "name": "write_file",
  "arguments": {
    "filePath": "/path/to/new-file.txt",
    "content": "Hello, World!",
    "createDirectories": true
  }
}

Listing a Directory

{
  "name": "list_directory",
  "arguments": {
    "dirPath": "/path/to/directory",
    "includeHidden": false
  }
}

Error Handling

All operations include comprehensive error handling:

• Invalid paths are rejected with descriptive error messages
• Permission errors are clearly reported
• File not found errors include the attempted path
• Directory traversal attempts are blocked

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 if applicable
5. Submit a pull request

Support

For issues and questions, please create an issue in the repository.