内容
# 文件系统 MCP Server
一个强大的文件系统管理服务器，使用 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` 目录中的默认位置。
用法示例：
```python
# 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 only)
- WMI (Windows only)
要安装依赖项：
```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 # On Windows: venv\Scripts\activate
```
3. 安装依赖项：
```bash
pip install -r requirements.txt
```
## 用法
有关跨不同开发环境（Claude、Cursor、Windsurf）的详细 MCP 配置说明，请访问：
[MCP Configuration Guide](https://calebmwelsh.github.io/Configure-MCP/)
### 与 Claude 集成
要将文件系统 MCP server 与 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 (Command Prompt/Terminal):**
```cmd
where python
```
**Linux/macOS (Terminal):**
```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. Fork 存储库
2. 创建一个功能分支
3. 提交您的更改
4. 推送到分支
5. 创建一个 Pull Request
## 许可证
此项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。
## 致谢
- 使用 FastMCP 构建
- 使用 Pydantic 进行数据验证
- 灵感来自现代文件系统管理工具
MCP 市场