What is Trash Cleaner Mcp Server

trash-cleaner-mcp-server is a desktop MCP service designed to scan for and remove junk files, helping to keep your system clean and optimized, primarily for macOS.

Use cases

Use cases include regular system maintenance for macOS users, cleaning up application caches and temporary files, managing VS Code extensions, and automating cleaning tasks.

How to use

To use trash-cleaner-mcp-server, install the service on your macOS system, then utilize the provided tools to scan and clean junk files. You can also schedule tasks for automated cleaning.

Key features

Key features include intelligent scanning for various junk file types, selective cleaning options, VS Code extension management, filesystem utilities, system information detection, audit logging, and scheduled tasks.

Where to use

trash-cleaner-mcp-server is primarily used in personal and professional environments where macOS systems are prevalent, focusing on maintaining system performance and cleanliness.

trash-cleaner-mcp-server

中文 README

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 MCP via bunx:

bunx @childhoodandy/trash-cleaner-mcp-server

Installation

# Clone the repository
git clone <repository-url>
cd trash-cleaner-mcp-server

# Install dependencies (using Bun)
bun install

Running the Server

bun start

Configuration

• Logging configuration is in src/utils/logger.ts.
• Scheduled task definitions are stored in ~/.trash-cleaner/schedules.json.

Development

(Development guidelines remain here…)