文件系统 MCP 服务器

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

平台支持

该服务器设计用于跨不同的操作系统运行，但具有不同级别的功能：

视窗

• 完整功能支持

• 驱动器列表

• 特殊文件夹访问

• Windows 特定的路径处理

• 详细系统信息

macOS/Linux

• 基本文件操作

• 目录操作

• 文件搜索和元数据

• 基本系统信息

• 注意：某些 Windows 特定功能不可用

Related MCP server: MCP Local File Reader

未来实施

计划中的 macOS 支持

• macOS 的本机路径处理

• macOS 特定的系统信息检索

• 与 macOS 文件系统功能集成

• 支持 macOS 特定的文件属性

• 实现 macOS 特定的实用程序（类似于 windows_utils.py）

计划中的 Linux 支持

• Linux 的本机路径处理

• Linux 特定的系统信息检索

• 与 Linux 文件系统功能集成

• 支持Linux文件权限和属性

• Linux 特定实用程序的实现

跨平台改进

• 统一路径处理系统

• 与平台无关的驱动器检测

• 一致的系统信息API

• 跨平台标准化文件属性

• 跨平台文件系统事件监控

• 通用文件收集系统

时间线

• 第一阶段：基本跨平台兼容性改进

• 第 2 阶段：平台特定功能实现

• 第三阶段：高级跨平台功能

• 第四阶段：性能优化和改进

特征

文件操作

• 使用备份支持复制文件

• 使用备份支持移动文件

• 删除带有安全检查的文件

• 读取文件内容

• 写入文件内容

• 获取文件信息（大小、创建时间、修改时间）

• 按名称模式搜索文件

• 创建文件集合以组织相关文件

目录操作

• 列出目录内容

• 创建目录

• 删除目录

• 递归列出目录（树状结构）

• 按名称模式搜索目录

系统信息

• 获取系统信息（操作系统、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

• 派丹蒂克

• 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 配置指南

与克劳德的整合

要将文件系统 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. 重启克劳德

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. 创建拉取请求

执照

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。

致谢

• 使用 FastMCP 构建

• 使用 Pydantic 进行数据验证

• 受到现代文件系统管理工具的启发