File Organizer MCP

文件管理器MCP服务器

版本： 3.4.2 | MCP协议： 2024-11-05 | 节点： ≥18.0.0

v3.3.0中的新功能-智能组织：

• organize_smart -自动检测和组织混合文件夹（音乐、照片、文档）
• organize_music -具有ID3元数据的按艺术家/专辑结构的音乐
• organize_photos -照片由EXIF日期与GPS剥离
• organize_by_content -按主题提取文档
• batch_read_files -高效读取多个文件

上一个v3.2.8版本：

• 增强的元数据提取、安全筛查和元数据缓存系统

为什么选择专业工具 • 快速开始 • 特性 • 工具 • 例子 • API • 安全 • 建筑

______________________________________________________________________

](https://www.npmjs.com/package/file-organizer-mcp) ](https://www.npmjs.com/package/file-organizer-mcp)  ](https://nodejs.org)  

用于智能文件组织的强大、安全强化的模型上下文协议（MCP）服务器。

______________________________________________________________________

为什么选择文件管理器MCP？

传统的文件系统MCP服务器提供基本工具： read, write, make, delete当AI仅使用这些工具组织文件夹时，它会导致：

1. 复杂性 -AI必须为每次移动和重命名计划多个步骤。
2. 令牌效率低下 -描述每个操作都会消耗大量的上下文。
3. 幻觉风险 -增加步数会增加出错的概率。
4. 延迟 -每个原始操作都需要独立的推理。

解决方案

我们提供封装复杂文件操作的高级原子工具：

______________________________________________________________________

快速开始

一个命令设置

运行以下命令以启动交互式设置：

npx file-organizer-mcp --setup

向导将：

• 自动检测已安装的AI客户端（Claude Desktop、Cursor、Windsurf、Cline等）。
• 自动配置客户端。
• 指导您完成文件夹选择和首选项设置。

需求

• Node.js 18+

常用命令

配置后，您可以询问您的AI：

• “整理我的下载文件夹”
• “在我的文档中查找重复文件”
• “显示我最大的文件”

安装方法

______________________________________________________________________

特性

• 分类 -智能分类为12+个类别。
• 调度 -基于Cron的自动组织。
• 重复检测 -内容哈希（SHA-256）用于精确识别。
• 元数据抽取 -EXIF用于照片，ID3用于音乐和文档主题提取。
• 智能组织 -检测混合文件类型的统一策略。
• 安全操作 -干运行模式、回滚支持和原子移动。
• 安全 -TOCTU缓解、路径遍历保护和元数据清理。
• 多平台 -原生支持Windows、macOS和Linux。

______________________________________________________________________

工具参考

核心工具

file_organizer_scan_directory

扫描包含详细文件信息的目录。

• directory （必填）：目录的完整路径。
• include_subdirs （可选）：递归扫描。

file_organizer_read_file

通过8层验证实现安全的文件读取。

• path （必填）：绝对路径。
• encoding （可选）：utf-8、base64或二进制。

file_organizer_organize_smart

使用最佳策略自动处理音乐、照片和文档的统一工具。

file_organizer_batch_rename

使用模式、正则表达式或编号重命名多个文件。

file_organizer_undo_last_operation

反转之前的组织操作。

______________________________________________________________________

文件类别

______________________________________________________________________

示例工作流

智能下载清理

1. 扫描 ->检查文件分发和空间使用情况。
2. 分析 ->识别重复和过时的文件。
3. 执行 ->将原子组织到分类文件夹中。
4. 查找重复项→ 找到45个重复组，浪费了2.3 GB
5. 显示最大的文件→ old_backup.zip：5.2 GB
6. 预览组织→ 显示计划的移动和冲突
7. 请求确认
8. 整理文件→ ✅ 将1247个文件组织到8个类别文件夹中

结果：干净、有序的下载文件夹，已识别出重复项

---

### Workflow 2: Project Organization

用户：“Claude，将我的项目文件夹组织到~/myproject”

克劳德：

1. 扫描项目→ 423 跨多个子目录的文件
2. 标识文件类型→ 代码（289）、资产（87）、文件（47）
3. 建议组织→ 保留src/结构，组织根文件
4. 预览更改→ 显示（47）个要组织的项目
5. 执行→ 将配置文件、阅读、屏幕截图移动到适当的文件夹

结果：通过有组织的文件和资产清理项目结构

---

### Workflow 3: Duplicate File Management

用户：“Claude，在C:/Users/\[YOUR_USERNAME\]/Documents中查找并分析重复项”

克劳德：

1. 扫描重复项→ 找到23个重复组
2. 分析每个组→ 按位置、名称质量、年龄对文件进行评分
3. 建议保留哪一个→ 保留“/文档/重要/文件.pdf”
4. 建议删除哪个→ 删除“/下载/文件（1）.pdf”
5. 显示浪费的空间→ 总计：可回收1.8 GB

用户可以手动删除或要求Claude组织删除重复项

---

### Workflow 4: Large File Discovery

用户：“克劳德，给我看看下载文件夹中占用空间最大的20个文件”

克劳德：

1. 分析目录大小→ 总计：45.2 GB
2. 查找最大的文件：

- old_backup_2023.zip：12.3 GB（2岁） - movie_collection.mkv:8.7 GB - 演示文稿_最终.pptx:890 MB

1. 建议清理→ 存档或删除旧备份
2. 显示大文件中的重复项→ 一些大文件有副本

结果：通过可操作的见解清晰地了解空间使用情况

---

### Workflow 5: Music Organization

用户：“Claude，将我的音乐文件夹组织在C:/Users/\[YOUR_USERNAME\]/music”

克劳德：

1. 扫描目录→ 显示456个音乐文件，2.3 GB
2. 提取元数据→ 读取艺术家、专辑和标题的ID3标签
3. 预览组织→ 显示计划结构：艺术家/专辑/Title.mp3
4. 请求确认
5. 整理文件→ ✅ 将456个音乐文件整理到32个艺术家文件夹中

结果：使用ID3元数据按艺术家/专辑/标题结构组织的音乐文件

之前： ├── 下载专区/ │ ├── 歌曲1.mp3 │ ├── track02.mp3 │ └── 音乐文件.mp3

之后： ├── 音乐/ │ ├── 酷玩乐队/ │ │ ├── 鲜血涌向头部/ │ │ │ ├── 时钟.mp3 │ │ │ └── 科学家.mp3 │ └── 无线电头/ │ ├── OK电脑/ │ │ ├── 偏执狂Android.mp3 │ │ └── Karma Police.mp3

---

### Workflow 6: Photo Organization

用户：“克劳德，把我的照片整理到C:/Users/\[YOUR_USERNAME\]/Pictures”

克劳德：

1. 扫描目录→ 显示1234张照片，4.5 GB
2. 提取EXIF元数据→ 从EXIF标签中读取日期
3. 预览组织→ 显示计划结构：YYYY/MM/DD
4. 请求确认
5. 整理文件→ ✅ 将1234张照片整理到基于日期的文件夹中

结果：使用EXIF元数据按拍摄日期（YYYY/MM/DD）组织照片

之前： ├── 图片/ │ ├── IMG_001.jpg │ ├── 照片123.png │ └── DSC_4567.raw

之后： ├── 图片/ │ ├── 2023/ │ │ ├── 12/ │ │ │ ├── 25/ │ │ │ │ ├── IMG_001.jpg │ │ │ └── 31/ │ │ │ └── 照片123.png │ └── 2024/ │ ├── 01/ │ │ └── 15/ │ │ └── DSC_4567.raw

---

### Workflow 7: Security Screening with Metadata

用户：“Claude，扫描我的Documents文件夹以查找安全问题”

克劳德：

1. 扫描目录→ 显示567个文档，1.2 GB
2. 提取元数据→ 读取文件元数据和内容签名
3. 执行安全检查→

- 找到3个包含敏感元数据的文件 - 发现1个包含潜在恶意内容的文件

1. 显示详细报告→

- “report.pdf”包含EXIF GPS坐标 - “resume.docx”包含个人身份信息

1. 建议采取行动→ 修改元数据、隔离文件

结果：基于元数据的威胁检测的全面安全扫描

---

### Workflow 8: Set Up Automatic Organization

用户：“克劳德，每天早上9点自动整理我的下载文件夹”

克劳德：

1. 设置监视目录→

file_organizer_watch_directory({ 目录：“/Users/john/Downloads”， 时间表：“0 9\*\*\*”， 分钟_时间_分钟：5 })

1. 确认设置→ “下载文件夹将于每天上午9:00整理”
2. 显示当前手表→ 列出所有关注的目录

用户：“还要每小时查看一次我的桌面文件夹”

克劳德： 4.添加第二块手表→ file_organizer_watch_directory({ 目录：“/Users/john/Desktop”， 时间表：“0\*\*\*\*”， max_files_per-run：50 })

结果：具有智能调度的自动后台组织

---

## Security Configuration 🔐

### Security Score: 10/10 🌟

The server uses a **Secure by Default** approach. Access is restricted to a specific whitelist of user directories. All system directories are blacklisted.

### ✅ Allowed Directories (Default)

The server automatically detects and allows access to these safe user locations:

| Platform    | Allowed Directories                                                                                     |
| ----------- | ------------------------------------------------------------------------------------------------------- |
| **Windows** | `Desktop`, `Documents`, `Downloads`, `Pictures`, `Videos`, `Music`, `OneDrive`, `Projects`, `Workspace` |
| **macOS**   | `Desktop`, `Documents`, `Downloads`, `Movies`, `Music`, `Pictures`, `iCloud Drive`, `Projects`          |
| **Linux**   | `Desktop`, `Documents`, `Downloads`, `Music`, `Pictures`, `Videos`, `~/dev`, `~/workspace`              |

_> Note: Only directories that actually exist on your system are enabled._

### ❌ Always Blocked

To prevent accidents, the following are **always blocked**, even if added to config:

- **Windows:** `C:\Windows`, `Program Files`, `AppData`, `$Recycle.Bin`
- **macOS:** `/System`, `/Library`, `/Applications`, `/private`, `/usr`
- **Linux:** `/etc`, `/usr`, `/var`, `/root`, `/sys`, `/proc`
- **Global:** `node_modules`, `.git`, `.vscode`, `.idea`, `dist`, `build`

### ⚙️ Custom Configuration

You can customize behavior by editing the user configuration file.

**Config Location:**

- **Windows:** `%APPDATA%\file-organizer-mcp\config.json`
- **macOS:** `$HOME/Library/Application Support/file-organizer-mcp/config.json`
- **Linux:** `$HOME/.config/file-organizer-mcp/config.json`

**How to Add Directories:**

1. Open `config.json`
2. Add paths to `customAllowedDirectories`:

{ "customAllowedDirectories": [ "C:\\Users\\Name\\My Special Folder", "D:\\Backups" ] }

> 💡 **提示：** 您可以直接从文件资源管理器的地址栏复制文件夹路径并将其粘贴到 `customAllowedDirectories`.

#### 💾 外部驱动器和网络安装

默认情况下，出于安全原因，您不能在主目录之外添加路径。如果您需要访问外部卷（如 `/Volumes/My Drive` 在macOS或 `/media/user/usb` 在Linux上），您必须通过添加来明确选择加入 `"allowExternalVolumes": true`:

{ "allowExternalVolumes": true, "customAllowedDirectories": [ "/Volumes/MyExternalDrive", "/Volumes/Photography Backup" ] }

_（注意：Windows驱动器字母如 `D:\` 开箱即用，不需要这个标志。)_

3. 重新启动克劳德桌面。

### 冲突策略

设置您首选的默认冲突解决策略：

{ "conflictStrategy": "rename" }

可用策略：

- `"rename"` （默认）-重命名新文件（例如。， `file (1).txt`)
- `"skip"` -保留现有文件，跳过新文件
- `"overwrite"` -替换现有文件（首先创建备份）

### 自动组织时间表（旧版）

简单的时间表配置（基本小时/日/周）：

{ "autoOrganize": { "enabled": true, "schedule": "daily" } }

对于基于cron的高级调度，请使用 `file_organizer_watch_directory` 工具。

### 安全防御

|攻击类型|防护机制|状态|
| ----------------------- | ------------------------------------ | ------------ |
| **未经授权的访问** |白名单+黑名单执行|✅ 受保护|
| **路径遍历** |8层验证管道|✅ 受保护|
| **Symlink攻击** |真实路径分辨率|✅ 受保护|
| **拒绝服务** |资源限制（文件、深度、大小）|✅ 受保护|

______________________________________________________________________

## 🐛 故障排除

### MCP服务器未显示

1. ✅ 检查配置文件路径是否正确
1. ✅ 验证是否安装了Node.js v18+： `node --version`
1. ✅ 完全重新启动克劳德桌面
1. ✅ 检查路径 `claude_desktop_config.json` 是正确的

### 权限错误

1. ✅ **窗户：** 以管理员身份运行Claude Desktop
1. ✅ **Mac/Linux：** 检查文件夹权限： `ls -la`
1. ✅ 确保目标目录中的写入权限

### 文件未移动

1. ✅ 验证 `dry_run` 模式未启用
1. ✅ 检查文件是否未被其他程序锁定
1. ✅ 确保有足够的磁盘空间
1. ✅ 查看操作摘要中的错误消息

## 技术栈🛠️

File Organizer MCP采用现代web技术构建，并遵循严格的安全实践：

### 核心依赖关系

- **MCP服务器：** `@modelcontextprotocol/sdk` -模型上下文协议实现
- **安全：** Zod模式验证、路径遍历保护
- **元数据提取：**
  - `music-metadata` -音频文件的ID3标签提取
  - `exif-parser` -图像的EXIF元数据提取
- **行程安排：** `node-cron` -基于Cron的进度管理
- **交互式用户界面：** Ink+React-终端用户界面
- **提示：** `@inquirer/prompts` -交互式CLI提示
- **公用设施：** 粉笔（彩色）、迷你火柴（球状图案）

### 安全特性

- **8层路径验证** -阻止遍历攻击和URI编码技巧
- **敏感文件检测** -阻止访问.env、.ssh、密码、密钥
- **速率限制** -120个请求/分钟，2000个请求/小时
- **TOCTU保护** -基于文件描述符的操作
- **元数据安全** -编辑敏感元数据（GPS、个人信息）

### 性能优化

- **元数据缓存** -7天缓存，带文件哈希验证
- **并行处理** -批处理操作的可配置并发性
- **流处理** -处理大文件而不会出现内存问题
- **内存限制** -防止资源过度消耗

______________________________________________________________________

## 建筑🏗️

### 屏幕然后丰富架构

文件管理器MCP服务器实现了“Screen Then Enrich”架构，以实现安全高效的文件操作：

┌───────────────────────────────────────────────────────────┐ │ MCP Client (LLM) │ └─────────────────────────┬─────────────────────────────────┘ │ JSON-RPC 2.0 ┌─────────────────────────▼─────────────────────────────────┐ │ MCP Server Layer │ │ (server.ts - Protocol Handler) │ └─────────────────────────┬─────────────────────────────────┘ │ ┌─────────────────────────▼─────────────────────────────────┐ │ Security Screening │ │ - Path validation & containment checks │ │ - Sensitive file detection │ │ - Rate limiting │ └─────────────────────────┬─────────────────────────────────┘ │ ┌─────────────────────────▼─────────────────────────────────┐ │ Metadata Enrichment │ │ - EXIF extraction for images (camera, date, GPS) │ │ - ID3 extraction for audio (artist, album, title) │ │ - Document metadata (PDF, DOCX properties) │ └─────────────────────────┬─────────────────────────────────┘ │ ┌─────────────────────────▼─────────────────────────────────┐ │ Services Layer │ │ ┌────────────┬──────────────┬─────────────┬──────────┐ │ │ │ Path │ Organizer │ Hash │ Scanner │ │ │ │ Validator │ Service │ Calculator │ Service │ │ │ └────────────┴──────────────┴─────────────┴──────────┘ │ └─────────────────────────┬─────────────────────────────────┘ │ ┌─────────────────────────▼─────────────────────────────────┐ │ File System │ └───────────────────────────────────────────────────────────┘

### 关键架构原则

1. **安全第一** -在任何文件操作之前进行多层验证
1. **元数据驱动** -使用提取的元数据的内容感知组织
1. **缓存策略** -7天元数据缓存，带文件哈希验证
1. **批处理** -大型操作的可配置并发性
1. **原子操作** -支持回滚的安全文件操作

______________________________________________________________________

## API文档📚

### 新元数据API

#### `file_organizer_inspect_metadata`

**说明：** 从具有隐私控制的文件中提取全面的元数据

**参数：**

- `file`：string（必需）-文件的完整路径
- `response_format`：json | markdown（可选，默认：markdown）

**退货：**

- 对于图像：EXIF数据（相机、日期、尺寸、ISO、光圈）
- 音频：ID3标签（艺术家、专辑、标题、年份、流派）
- 对于文档：文件属性

#### 元数据缓存系统

**配置：**

{ "metadataCache": { "enabled": true, "maxAge": 604800000, // 7 days in ms "maxEntries": 10000, "cacheDir": ".cache" } }

**缓存统计信息：**

// Get cache statistics const stats = await getCacheStats(); // { // totalEntries: 1500, // audioEntries: 800, // imageEntries: 700, // cacheSize: 256000 // }

______________________________________________________________________

## 📝 重要说明

- ⚠️ 在中组织文件 **仅限根目录**，而不是子目录（默认情况下）
- ⚠️ 不会重新组织现有类别文件夹（防止循环）
- ✅ 文件扩展名不区分大小写
- ✅ 保留原始修改日期
- ✅ 隐藏文件（以开头 `.`)自动跳过
- ✅ 每次操作最多处理10000个文件（安全限制）
- ✅ 最多扫描10个目录级别（安全限制）
- ✅ 对撤消操作的回滚支持

______________________________________________________________________

## 🤝 贡献

欢迎投稿！请阅读 [贡献.md](CONTRIBUTING.md) 作为指导方针。

### 开发环境

git clone https://github.com/kridaydave/File-Organizer-MCP.git cd File-Organizer-MCP npm install npm run build npm test

### 报告问题

🚨 **安全漏洞：** 电子邮件technocratix902@gmail.com\
🐛 **缺陷/功能：** 

______________________________________________________________________

## 📚 文档

- **[API毫米](API.md)** -完整的工具参考
- **[建筑.md](ARCHITECTURE.md)** -技术架构和设计模式
- **[贡献.md](CONTRIBUTING.md)** -贡献指南
- **[MIGRATION.md](MIGRATION.md)** -v2到v3升级指南
- **[更改日志.md](CHANGELOG.md)** -版本历史

______________________________________________________________________

## 📄 许可证

MIT许可证-请参阅 [许可证](LICENSE) 详细信息文件

______________________________________________________________________

## 🙏 致谢

- **Anthropic** -对于模型上下文协议规范
- **网络Chuck** -对于启发此项目的MCP教程
- **MCP社区** -获取反馈和支持

______________________________________________________________________

## 📞 支持

- **MCP注册表：** [查看列表](https://registry.modelcontextprotocol.io/servers/io.github.kridaydave/file-organizer)
- **NPM包：** 
- **问题：** 
- **MCP规范：** [模型上下文协议](https://modelcontextprotocol.io)

______________________________________________________________________

### 组织愉快！ 🎯

> _内置于❤️ 对于MCP社区_

[⬆ 返回顶部](#file-organizer-mcp-server)