File System MCP Server

文件系统 MCP 服务

一个使用 FastMCP 构建的强大文件系统管理服务，提供全面的文件和目录操作工具集。此服务允许你通过结构化 API 执行各种文件系统操作，非常适合用于自动化以及与其他系统集成。

平台支持

此服务旨在适用于不同的操作系统，但各平台支持的功能有所不同：

Windows

• 完整功能支持
• 驱动器列表
• 访问特殊文件夹
• Windows 专用路径处理
• 详细的系统信息

macOS/Linux

• 基本文件操作
• 目录操作
• 文件搜索和元数据
• 基本系统信息
• 注意：不支持某些 Windows 专属功能

未来实现

计划支持 macOS

• macOS 原生路径处理
• 获取 macOS 专用系统信息
• 集成 macOS 文件系统功能
• 支持 macOS 专用文件属性
• 实现 macOS 专用工具（类似于 windows_utils.py）

计划支持 Linux

• Linux 原生路径处理
• 获取 Linux 专用系统信息
• 集成 Linux 文件系统功能
• 支持 Linux 文件权限和属性
• 实现 Linux 专用工具

跨平台改进

• 统一的路径处理系统
• 与平台无关的驱动器检测
• 一致的系统信息 API
• 跨平台标准化文件属性
• 跨平台文件系统事件监控
• 通用文件收集系统

时间线

• 阶段 1：基本跨平台兼容性改进
• 阶段 2：平台专属功能实现
• 阶段 3：高级跨平台功能
• 阶段 4：性能优化和完善

功能

文件操作

• 复制文件并支持备份
• 移动文件并支持备份
• 通过安全检查删除文件
• 读取文件内容
• 写入文件内容
• 获取文件信息（大小、创建时间、修改时间）
• 按名称模式搜索文件
• 创建文件集合，用于整理相关文件

目录操作

• 列出目录内容
• 创建目录
• 删除目录
• 递归列出目录（树状结构）
• 按名称模式搜索目录

系统信息

• 获取系统信息（操作系统、CPU、内存、磁盘使用情况）
• 获取磁盘信息（总空间、已用空间、可用空间）
• 获取目录信息（文件数、总大小）

项目结构

file-system-mcp-server/
├── fs_server.py            # Main server implementation
├── windows_utils.py        # Windows-specific utilities (Windows only)
├── requirements.txt        # Project dependencies
└── test_prompts_example.md # Example test prompts

集合存储

集合可以存储在用户指定的任何目录中。如果未指定存储位置，集合将存储在项目的 data/collections 目录中的默认位置。

用法示例：

# Store in default location
create_collection("my_collection", ["file1.txt", "file2.txt"])

# Store in custom location
create_collection("my_collection", ["file1.txt", "file2.txt"], storage_path="/path/to/store")

依赖项

必需依赖项

• FastMCP
• Pydantic
• pywin32（仅限 Windows）
• WMI（仅限 Windows）

安装依赖项：

pip install -r requirements.txt

设置

1. 克隆仓库：

git clone https://github.com/calebmwelsh/file-system-mcp-server.git
cd file-system-mcp-server

2. 创建并激活虚拟环境：

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. 安装依赖项：

pip install -r requirements.txt

用法

如需了解 Claude、Cursor、Windsurf 等不同开发环境的详细 MCP 配置说明，请访问： MCP 配置指南

与 Claude 集成

要将文件系统 MCP 服务与 Claude 集成，请将以下内容添加到 claude_desktop_config.json 文件中：

{
  "mcpServers": {
    "file-system": {
      "command": "/absolute/path/to/python",
      "args": [
        "/absolute/path/to/file-system-mcp-server/fs_server.py"
      ]
    }
  }
}

查找 Python 路径

要查找 Python 可执行文件的路径，请使用以下命令：

Windows（PowerShell）：

(Get-Command python).Source

Windows（命令提示符/终端）：

where python

Linux/macOS（终端）：

which python

将 /absolute/path/to/python 替换为上述相应命令的输出。

示例配置

对于 Windows，配置可能如下所示：

{
  "mcpServers": {
    "file-system": {
      "command": "C:\\Users\\YourUsername\\AppData\\Local\\Programs\\Python\\Python39\\python.exe",
      "args": [
        "C:\\Users\\YourUsername\\Documents/file-system-mcp-server/fs_server.py"
      ]
    }
  }
}

对于 macOS/Linux：

{
  "mcpServers": {
    "file-system": {
      "command": "/usr/local/bin/python3",
      "args": [
        "/Users/YourUsername/Documents/file-system-mcp-server/fs_server.py"
      ]
    }
  }
}

添加配置后：

1. 保存 claude_desktop_config.json 文件
2. 重启 Claude
3. 现在可以让 Claude 执行文件操作来使用文件系统工具

可用工具

文件操作

• copy_file：复制文件，可选择创建备份
• move_file：移动文件，可选择创建备份
• delete_file：删除文件，并进行安全检查
• read_file：读取文件内容
• write_file：向文件写入内容
• get_file_info：获取详细的文件信息
• search_files：按名称模式搜索文件
• create_collection：创建文件集合

目录操作

• list_directory：列出目录内容
• create_directory：创建新目录
• delete_directory：删除目录
• list_directory_recursively：以树形格式显示目录结构
• search_directories：按名称模式搜索目录

系统信息

• get_system_info：获取系统信息
• get_disk_info：获取磁盘使用情况
• get_directory_info：获取目录统计信息

已知问题

以下功能目前存在问题，可能无法按预期工作：

1. 删除文件功能

   • delete_file 函数在某些情况下可能无法正确删除文件
   • 建议用户手动确认文件是否已删除；在关键情况下，也可以使用其他方法
   • 该问题正在调查中，并将在未来的更新中修复

2. 列出驱动器功能

   • list_drives 函数可能无法正确检测或显示所有可用驱动器
   • 列表中可能缺少某些驱动器，或显示的信息不正确
   • 这是一个已知限制，将在未来的更新中解决

3. 平台特定限制

   • macOS/Linux 上无法使用 Windows 特定功能
   • 不同平台的某些路径处理方式可能有所不同
   • 获取系统信息的方式因平台而异

错误处理

该服务包含全面的错误处理，涵盖：

• 无效文件路径
• 文件/目录不存在
• 权限问题
• 磁盘空间限制
• 无效操作
• 平台特定错误

安全性

• 所有文件操作都会验证路径
• 在执行破坏性操作前会创建备份文件
• 系统信息访问仅限于安全操作
• 文件操作均经过适当的错误处理

贡献

1. Fork 此仓库
2. 创建功能分支
3. 提交更改
4. 将更改推送到该分支
5. 创建拉取请求

许可证

本项目采用 MIT License 授权，详情请参阅 LICENSE 文件。

致谢

• 使用 FastMCP 构建
• 使用 Pydantic 进行数据验证
• 灵感来自现代文件系统管理工具