trash-cleaner-mcp-server
About
A desktop MCP service that scans for and removes junk files to keep your system clean and optimized.
Details
- Author
- dabing1022
- GitHub stars
- 2
- Downloads
- 209
- Categories
- Other
Jump to
- Intelligent scanning of junk files (caches, logs, temp files)
- Selective cleaning for application caches, temp files, and remnants
- VS Code extension management (find and clean outdated extensions)
- Filesystem utilities (directory analysis, file finding, size calculation, deletion)
- System information detection (OS type)
- Audit logging with view and clear tools
- Scheduled task system with cron or interval-based execution
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
trash-cleaner-mcp-serverCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
The server can be run using bunx @childhoodandy/trash-cleaner-mcp-server or npx @childhoodandy/trash-cleaner-mcp-server. For development, clone the repository, run bun install, then bun start. Configuration for logging is in src/utils/logger.ts and scheduled task definitions are stored at ~/.trash-cleaner/schedules.json. The server registers numerous tools callable via MCP, with most cleaning tools marked as macOS-only.
TrashCleaner_Os_GetSystemType
获取当前操作系统的类型（例如：darwin, win32, linux）。
TrashCleaner_Fs_GetFolderSize
获取指定文件夹的大小（字节）。
TrashCleaner_Fs_ListDirectory
列出指定目录下的所有文件和子目录。
TrashCleaner_Fs_FindFiles
在指定目录中查找符合条件的文件。
TrashCleaner_Fs_FindPaths
在指定目录中查找符合条件的文件和文件夹。
TrashCleaner_Fs_FindDirectories
在指定目录中查找符合条件的文件夹。
TrashCleaner_Fs_AnalyzeDirectory
分析目录中文件的类型分布、大小分布等信息。
TrashCleaner_Fs_GetFileHash
计算文件的 MD5/SHA256 哈希值，用于文件完整性校验。
TrashCleaner_Fs_GetFileType
获取文件的MIME类型和基本信息。
TrashCleaner_Fs_DeletePath
删除指定文件或文件夹。默认永久删除，可通过 useTrash 选项移到系统垃圾桶。需用户确认。
TrashCleaner_Fs_CheckPathExists
检查指定的文件或目录路径是否存在。
TrashCleaner_Fs_EmptyTrash
清空操作系统垃圾桶。这是一个不可恢复的操作！请谨慎使用。
TrashCleaner_Cleaner_MacOSWarning
显示当前系统不是 macOS 的警告信息。
TrashCleaner_Cleaner_CleanAppCaches
清理各种应用程序缓存文件，包括用户缓存目录、应用程序保存的状态等。仅适用于 macOS 系统。
TrashCleaner_Cleaner_CleanTempFiles
清理系统临时文件目录中的临时文件。仅适用于 macOS 系统。
TrashCleaner_Cleaner_CleanAppRemnants
清理已卸载应用程序的配置文件、缓存和其他残留文件。仅适用于 macOS 系统。
TrashCleaner_Cleaner_SmartCleanSystem
智能清理系统垃圾文件，支持不同的清理级别。仅适用于 macOS 系统。
TrashCleaner_Cleaner_CleanVSCodeExtensions
清理 VSCode 及相关编辑器的低版本扩展。
TrashCleaner_Cleaner_ReportVSCodeExtensions
生成 VSCode 及相关编辑器低版本扩展的报告。
TrashCleaner_Cleaner_FindLargeFiles
在指定目录中查找超过指定大小的大文件。
TrashCleaner_Scan_ScanFullSystem
执行全盘扫描，识别文件分布和大小情况
TrashCleaner_Scan_ScanDirectory
扫描指定目录，分析文件分布和大小情况
TrashCleaner_Scan_ScanJunkFiles
扫描常见类型的垃圾文件 (缓存, 临时文件, 日志等)。依赖于 junk_rules.json 配置文件。
TrashCleaner_Audit_ViewAuditLog
查看应用程序最近的运行日志（combined.log）。
TrashCleaner_Audit_ClearAuditLog
清空应用程序的主运行日志文件（combined.log）。这是一个破坏性操作，请谨慎使用！
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"trash-cleaner-mcp-server": {
"trash-cleaner-mcp-server": {
"command": "npx",
"args": [
"@childhoodandy/trash-cleaner-mcp-server"
]
}
}
}
}McpServers
{
"trash-cleaner-mcp-server": {
"command": "npx",
"args": [
"@childhoodandy/trash-cleaner-mcp-server"
]
}
}trash-cleaner-mcp-server
A desktop MCP service providing tools to scan, analyze, and clean junk files, primarily optimized for macOS.
Note: Most cleaning tools (cleanAppCaches, cleanTempFiles, cleanAppRemnants, smartCleanSystem) are designed and tested specifically for macOS. Running them on other systems might not work or lead to unexpected behavior.
Features
Cross-Platform: (Planned) Windows, macOS, Linux support.
Intelligent Scanning: Identifies various types of junk files (caches, logs, temp files, etc.).
Selective Cleaning: Tools for cleaning specific areas like application caches, temp files, and application remnants.
VS Code Extension Management: Tools to find and clean old/unused VS Code extensions.
Filesystem Utilities: Tools for directory analysis, file finding, size calculation, deletion, etc.
System Information: Basic OS detection.
Audit Logging: Tracks operations via [Audit] tools.
Scheduled Tasks: Automate cleaning and other tasks using a flexible scheduler.
Define tasks using cron expressions or simple intervals.
Target any registered tool for execution.
Create/update tasks using exact tool names (toolName) or natural language queries (toolQuery) via fuzzy matching.
Full task management (list, details, update, enable/disable, delete).
Manual triggering and execution history tracking.
Available Tools (Features)
This server registers several tools callable via the MCP protocol:
macOS Cleaning Tools (Optimized for macOS):
macOSWarning: Displays a warning if run on a non-macOS system.
cleanAppCaches: Cleans various application caches (user cache, saved app state).
Options: dryRun (bool, default: true), olderThan (int, optional - days).
cleanTempFiles: Cleans system temporary files.
Options: dryRun (bool, default: true), olderThan (int, optional, default: 7 days).
cleanAppRemnants: Scans for and cleans configuration/cache files left by uninstalled applications.
Options: appName (string, optional - partial name match), dryRun (bool, default: true).
smartCleanSystem: Performs system cleaning based on predefined levels (targets common junk locations).
Options: cleanLevel (enum: "safe", "normal", "deep", default: "safe"), dryRun (bool, default: true).
Cross-Platform Tools (Scanning, File System, OS):
cleanVSCodeExtensions: Cleans outdated versions of VS Code (and compatible editors like VSCodium, Cursor) extensions.
Options: editorPath (string, optional - path to specific editor's extensions, default: scans all known locations), dryRun (bool, default: true).
reportVSCodeExtensions: Generates a report listing outdated VS Code extensions that can be cleaned.
Options: editorPath (string, optional).
findLargeFiles: Finds files exceeding a specified size within a directory.
Options: path (string), minSize (int, default: 100MB), maxDepth (int, default: 3).
scanFullSystem: Scans the entire system's file structure (respecting exclusions) to report on space usage.
Options: excludePaths (string[], optional), maxDepth (int, default: 10).
scanDirectory: Analyzes the contents and size distribution within a specific directory.
Options: path (string), excludePaths (string[], optional), maxDepth (int, default: 10), includeSubdirs (bool, default: true).
getFolderSize: Calculates and returns the total size of a folder.
Options: path (string).
listDirectory: Lists the files and subdirectories within a specified path.
Options: path (string), showHidden (bool, default: false).
findFiles: Searches for files matching a specific pattern (wildcards supported) within a directory.
Options: path (string), pattern (string), maxDepth (int, default: 5).
analyzeDirectory: Provides statistics on file types and size distribution within a directory.
Options: path (string), includeSubdirs (bool, default: true).
getFileHash: Computes the MD5, SHA1, or SHA256 hash of a file.
Options: path (string), algorithm (enum: "md5", "sha1", "sha256", default: "md5").
getFileType: Retrieves basic file information, including MIME type.
Options: path (string).
deletePath: Deletes a specified file or folder (requires explicit confirmation, with extra checks for dangerous paths).
Options: path (string), confirm (bool, must be true), dangerConfirm (bool, optional - required for potentially risky deletions).
checkPathExists: Checks if a given path exists and identifies if it's a file or directory.
Options: path (string).
getSystemType: Returns the operating system identifier (e.g., 'darwin', 'win32', 'linux').
Audit Tools:
viewAuditLog: Views the most recent lines from the application's main log file (combined.log).
Options: lines (int, default: 100, max: 1000).
clearAuditLog: Deletes the main application log file (combined.log). Requires confirmation.
Options: confirm (bool, must be true).
Scheduled Tasks (TrashCleaner_Scheduler Tools)
Provides functionality to schedule the execution of other registered tools.
TrashCleaner_Scheduler_CreateTask: Creates a new scheduled task.
Requires name, cronExpression.
Requires either toolName (exact tool name like "TrashCleaner_CleanAppCaches") or toolQuery (fuzzy description like "clean app caches").
Optional toolParams, enabled.
TrashCleaner_Scheduler_ListTasks: Lists all configured scheduled tasks and their status.
TrashCleaner_Scheduler_GetTaskDetails: Gets detailed information about a specific task by ID.
TrashCleaner_Scheduler_UpdateTask: Updates an existing task. Can modify name, schedule, target tool (via toolName or toolQuery), parameters, and enabled status.
TrashCleaner_Scheduler_EnableTask: Enables a disabled task.
TrashCleaner_Scheduler_DisableTask: Disables an enabled task.
TrashCleaner_Scheduler_DeleteTask: Permanently deletes a scheduled task.
TrashCleaner_Scheduler_RunTaskNow: Manually triggers the execution of a task immediately.
-
TrashCleaner_Scheduler_GetTaskHistory: Retrieves the recent execution history (success/failure) for a task.
Tech Stack
- Bun.js
- TypeScript
Usage
After publishing to npm, you can run the MCP server using either Bun or npm:Using Bun:
```sh
bunx @childhoodandy/trash-cleaner-mcp-server
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
