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中安装

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

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

# Install the binary
# 安装二进制文件
cargo install --path .

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)"来访问它。
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 | 贡献

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Run the test suite
Submit a pull request
Fork 仓库
创建功能分支
进行更改
为新功能添加测试
运行测试套件
提交拉取请求

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

filesystem-mcp-rust 0.0.2