trash-cleaner-mcp-server
About
A desktop MCP service that scans for and removes junk files to keep your system clean and optimized.
Details
- License
- MIT
Explore
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.
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
After publishing to npm, you can run the MCP server using either Bun or npm:
Using Bun:
bunx @childhoodandy/trash-cleaner-mcp-server
bunx -y @childhoodandy/trash-cleaner-mcp-server
Using npm:
npx @childhoodandy/trash-cleaner-mcp-server
bun install
bun start
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）。这是一个破坏性操作，请谨慎使用！
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).
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"
]
}
}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.
