文件系统MCP服务器

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

平台支持

该服务器设计为可在不同的操作系统上运行，但功能级别有所不同：

Windows

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

macOS/Linux

• 基本文件操作
• 目录操作
• 文件搜索和元数据
• 基本系统信息
• 注意：某些Windows特有的功能不可用

未来实现

计划中的macOS支持

• macOS原生路径处理
• macOS特定系统信息检索
• 与macOS文件系统特性的集成
• 支持macOS特定文件属性
• 实现macOS特定实用程序（类似于windows_utils.py）

计划中的Linux支持

• Linux原生路径处理
• Linux特定系统信息检索
• 与Linux文件系统特性的集成
• 支持Linux文件权限和属性
• 实现Linux特定实用程序

跨平台改进

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

时间线

• 第一阶段：基本跨平台兼容性改进
• 第二阶段：平台特定功能实现
• 第三阶段：高级跨平台功能
• 第四阶段：性能优化和改进

功能

文件操作

• 支持备份的文件复制
• 支持备份的文件移动
• 带有安全检查的文件删除
• 读取文件内容
• 写入文件内容
• 获取文件信息（大小、创建时间、修改时间）
• 按名称模式搜索文件
• 创建文件集合以组织相关文件

目录操作

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

系统信息

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

项目结构

file-system-mcp-server/
├── fs_server.py # 主服务器实现
├── windows_utils.py # Windows特定实用程序（仅限Windows）
├── requirements.txt # 项目依赖
└── test_prompts_example.md # 示例测试提示

集合存储

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

示例用法：
python

存储在默认位置

create_collection("my_collection", ["file1.txt", "file2.txt"])

存储在自定义位置

create_collection("my_collection", ["file1.txt", "file2.txt"], storage_path="/path/to/store")

依赖项

必需的依赖项

• FastMCP
• Pydantic
• pywin32 (仅限Windows)
• WMI (仅限Windows)

安装依赖项：
bash
pip install -r requirements.txt

设置

1. 克隆仓库：
   bash
   git clone https://github.com/calebmwelsh/file-system-mcp-server.git
   cd file-system-mcp-server

2. 创建并激活虚拟环境：
   bash
   python -m venv venv
   source venv/bin/activate # 在Windows上: venvScriptsactivate

3. 安装依赖项：
   bash
   pip install -r requirements.txt

使用

有关在不同开发环境（Claude, Cursor, Windsurf）中进行详细MCP配置说明，请访问：MCP 配置指南

与 Claude 的集成

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

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

查找 Python 路径

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

Windows (PowerShell):
powershell
(Get-Command python).Source

Windows (命令提示符/终端):
cmd
where python

Linux/macOS (终端):
bash
which python

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

示例配置

对于 Windows，您的配置可能如下所示：
json
{
"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:
json
{
"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. 平台特定的限制

   • Windows 特定的功能在 macOS/Linux 上不可用
   • 不同平台之间的路径处理可能有所不同
   • 系统信息检索因平台而异

错误处理

服务器包括对以下情况的全面错误处理：

• 无效的文件路径
• 文件/目录未找到
• 权限问题
• 磁盘空间限制
• 无效的操作
• 平台特定的错误

安全性

• 所有文件操作都包含路径验证
• 在破坏性操作之前创建备份文件
• 系统信息访问仅限于安全操作
• 文件操作带有适当的错误处理

贡献

1. 分叉仓库
2. 创建一个特性分支
3. 提交您的更改
4. 推送到分支
5. 创建一个 Pull Request

许可证

本项目根据 MIT 许可证发布 - 详情请参阅 LICENSE 文件。

致谢

• 使用 FastMCP 构建- 使用 Pydantic 进行数据验证
• 受现代文件系统管理工具的启发