Filesystem MCP Server

A Model Context Protocol (MCP) server for advanced filesystem operations with large file handling capabilities.

模型上下文协议 (MCP) 文件系统服务器，支持高级文件操作和大文件处理功能。

Current Version: 0.0.2 | 当前版本：0.0.2

⚠️ Important Notice for v0.0.2 | v0.0.2重要通知

Breaking Change: This version enforces absolute paths only for all file operations. Relative paths are no longer supported to enhance security. 破坏性变更：本版本强制要求所有文件操作必须使用绝对路径。不再支持相对路径以增强安全性。

Features | 功能特点

• Advanced File Operations: Read, write, delete, copy, move files with encoding support

• Directory Management: List, create, search directories recursively

• Large File Support: Sequential reading with offset and limit parameters

• Security: Path validation and allowed directories whitelist

• Metadata: File information including size, permissions, mime type, SHA-256 hash

• Multiple Encodings: Text and base64 encoding support

• MCP Protocol: Full JSON-RPC compliance for Claude Desktop integration

• 高级文件操作: 支持读取、写入、删除、复制、移动文件，支持多种编码

• 目录管理: 递归列出、创建、搜索目录

• 大文件支持: 支持偏移量和限制参数的序列化读取

• 安全性: 路径验证和允许目录白名单

• 元数据: 文件信息包括大小、权限、MIME类型、SHA-256哈希

• 多种编码: 支持文本和base64编码

• MCP协议: 完全符合JSON-RPC协议，支持Claude Desktop集成

Installation | 安装

Prerequisites | 前置要求

• Rust 1.70+ (install from rustup.rs)
• Claude Desktop (for MCP integration)

Build from Source | 从源码构建

# Clone the repository
# 克隆仓库
git clone https://gitee.com/awol2010ex/filesystem-mcp-rust.git
cd filesystem-mcp-rust

# Build the project
# 构建项目
cargo build --release

# Install locally
# 本地安装
cargo install --path .

Usage | 使用方法

Basic Usage | 基本用法

# Run the server
# 运行服务器
./target/release/filesystem-mcp-rust

# Or if installed via cargo install
# 或者通过cargo install安装后
filesystem-mcp-rust

Configuration | 配置

⚠️ Important: All paths must be absolute paths. Relative paths are not supported in v0.0.2+ ⚠️ 重要：所有路径必须是绝对路径。v0.0.2+版本不支持相对路径

The server accepts configuration through command line arguments:

服务器接受通过命令行参数进行配置：

# Set allowed directories (semicolon-separated)
# 设置允许的目录（分号分隔）
filesystem-mcp-rust /home/user/documents;/home/user/projects

# Use current directory (default)
# 使用当前目录（默认）
filesystem-mcp-rust

# Single directory
# 单个目录
filesystem-mcp-rust /home/user/workspaces

Note: The CREATE_BACKUP_FILES feature is automatically enabled for write operations to prevent accidental data loss. 注意：CREATE_BACKUP_FILES 功能在写入操作时会自动启用，以防止意外数据丢失。

MCP Integration | MCP集成

Install in Trae | 在Trae中安装

1. Build and install the MCP server 构建并安装MCP服务器

   # Build the project
   # 构建项目
   cargo build --release
   
   # Install the binary
   # 安装二进制文件
   cargo install --path .
   

2. Configure in Trae settings.json 在Trae的settings.json中配置

   Add the filesystem MCP server to your Trae settings.json configuration: 将文件系统MCP服务器添加到您的Trae settings.json 配置中：

   {
     "mcpServers": {
         "filesystem-mcp-rust": {
           "command": "filesystem-mcp-rust",
           "args": ["E:/workspaces"]
         }
       
     }
   }
   

   Note: Use absolute paths in the arguments. Example for Windows: E:/workspaces, for Linux/macOS: /home/user/workspaces 注意：在参数中使用绝对路径。Windows示例：E:/workspaces，Linux/macOS示例：/home/user/workspaces

   For multiple directories, use semicolon-separated paths: 对于多个目录，使用分号分隔的路径：

   {
     "mcp": {
       "servers": {
         "filesystem": {
           "command": "filesystem-mcp-rust",
           "args": ["/home/user/workspaces;/home/user/projects"]
         }
       }
     }
   }
   

   Note: The settings.json file is typically located in your Trae configuration directory. You can access it through Trae's command palette (Ctrl+Shift+P) and searching for "Preferences: Open Settings (JSON)". 注意：settings.json 文件通常位于您的Trae配置目录中。您可以通过Trae的命令面板（Ctrl+Shift+P）搜索"首选项：打开设置(JSON)"来访问它。

3. Verify installation 验证安装

   The filesystem operations should now be available in Trae's MCP tools. 文件系统操作现在应该在Trae的MCP工具中可用。

Testing | 测试

Run Tests | 运行测试

# Run all tests
# 运行所有测试
cargo test

# Run tests with output
# 运行测试并显示输出
cargo test -- --nocapture

# Run specific test
# 运行特定测试
cargo test test_read_file

Integration Testing | 集成测试

# Test basic file operations
# 测试基本文件操作
echo "test content" > test_file.txt
./target/release/filesystem-mcp-rust  # Start server in one terminal
# Then test MCP requests in another terminal

Development | 开发

Development Build | 开发构建

# Build for development
# 开发构建
cargo build

# Build with fast profile
# 使用快速配置文件构建
cargo build --profile fast

Code Quality | 代码质量

# Format code
# 格式化代码
cargo fmt

# Run linter
# 运行 linter
cargo clippy

# Check for security vulnerabilities
# 检查安全漏洞
cargo audit

API Reference | API参考

Supported Operations | 支持的操作

• read_file - Read file content with optional offset and limit

• write_file - Write content to file with encoding support

• delete_file - Delete file or directory

• list_directory - List directory contents

• search_files - Search files by name or content

• create_directory - Create new directory

• copy_file - Copy file to new location

• move_file - Move file to new location

• get_file_info - Get detailed file information

• get_disk_usage - Get disk usage statistics

• read_file - 读取文件内容，支持偏移量和限制

• write_file - 写入文件内容，支持编码

• delete_file - 删除文件或目录

• list_directory - 列出目录内容

• search_files - 按名称或内容搜索文件

• create_directory - 创建新目录

• copy_file - 复制文件到新位置

• move_file - 移动文件到新位置

• get_file_info - 获取详细的文件信息

• get_disk_usage - 获取磁盘使用统计

Security | 安全

• Path traversal protection

• Allowed directories whitelist

• File permission validation

• Safe encoding handling

• 路径遍历保护

• 允许目录白名单

• 文件权限验证

• 安全编码处理

Performance | 性能

• Optimized for large files with sequential reading

• Efficient directory traversal

• Minimal memory footprint for streaming operations

• Async I/O with Tokio

• 针对大文件的序列化读取优化

• 高效的目录遍历

• 流操作的最小内存占用

• 使用Tokio的异步I/O

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

7. Fork 仓库

8. 创建功能分支

9. 进行更改

10. 为新功能添加测试

11. 运行测试套件

12. 提交拉取请求

License | 许可证

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

本项目采用 Apache License 2.0 许可证 - 详见 LICENSE 文件。

Changelog | 更新日志

Version 0.0.2 (2025-12-19)

版本 0.0.2 (2025年12月19日)

Security Enhancement | 安全增强

• Breaking Change: Enforced absolute path requirement for all file operations
• 破坏性变更: 强制所有文件操作必须使用绝对路径
• Security: Disabled relative path support to prevent path traversal attacks
• 安全性: 禁用相对路径支持以防止路径遍历攻击

Changes | 变更

• All file operations now require absolute paths only
• 所有文件操作现在仅支持绝对路径
• Relative paths will be rejected with clear error message
• 相对路径将被拒绝并显示明确的错误信息

Impact | 影响

• Existing configurations using relative paths need to be updated
• 使用相对路径的现有配置需要更新
• Migration required for all MCP client configurations
• 需要迁移所有MCP客户端配置

Version 0.0.1 (Initial Release)

版本 0.0.1 (初始版本)

Features | 功能

• Basic filesystem operations (read, write, delete, copy, move)
• 基本文件系统操作（读取、写入、删除、复制、移动）
• Directory management (list, create, search)
• 目录管理（列出、创建、搜索）
• Large file support with streaming
• 支持大文件流式处理
• Multiple encoding support (UTF-8, base64)
• 多种编码支持（UTF-8、base64）
• Full MCP protocol compliance
• 完全符合MCP协议
• Path validation and security features
• 路径验证和安全功能

Support | 支持

For issues and questions:

• Create an issue on Gitee: https://gitee.com/awol2010ex/filesystem-mcp-rust/issues
• Contact: awol2005ex@163.com

对于问题和疑问：

• 在Gitee上创建问题：https://gitee.com/awol2010ex/filesystem-mcp-rust/issues
• 联系：awol2005ex@163.com