trash-cleaner-mcp-server

What is trash-cleaner-mcp-server?

trash-cleaner-mcp-server is a desktop MCP service that provides tools to scan, analyze, and clean junk files. It is primarily optimized for macOS, with cross-platform support (Windows, Linux) planned. The server is built with Bun.js and TypeScript and is intended for users who want to manage system clutter, application remnants, and temporary files programmatically via the Model Context Protocol.

How to use trash-cleaner-mcp-server?

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.

Key features of trash-cleaner-mcp-server

• 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

Use cases of trash-cleaner-mcp-server

• Clean application caches and temporary files on macOS with dry-run support
• Remove configuration and cache files left by uninstalled applications
• Identify and delete outdated VS Code extensions across editors like VSCodium and Cursor
• Find large files in a directory to free up disk space
• Automate regular system cleaning tasks using the built-in scheduler

FAQ from trash-cleaner-mcp-server

Which operating systems are supported?

Most cleaning tools (cleanAppCaches, cleanTempFiles, cleanAppRemnants, smartCleanSystem) are designed and tested specifically for macOS. Cross-platform support for Windows and Linux is planned. The server can report the operating system via getSystemType.

How do I schedule cleaning tasks?

Use the TrashCleaner_Scheduler tools. You can create a task by specifying a name, a cron expression, and either an exact toolName or a fuzzy toolQuery (e.g., "clean app caches"). Tasks can be listed, updated, enabled, disabled, deleted, triggered manually, and their execution history can be viewed.

Where are logs and scheduled task definitions stored?

Audit logs are written to a combined.log file. The viewAuditLog tool reads from this file. Scheduled task definitions are stored in ~/.trash-cleaner/schedules.json.

How can I safely delete files?

Use the deletePath tool. It requires explicit confirmation (confirm: true) and an additional dangerConfirm flag for potentially risky deletions. Extra checks are in place to prevent accidental deletion of critical paths.

What options are available for cleaning tools?

Most cleaning tools accept a dryRun option (default true) to preview changes without deleting. Some support an olderThan parameter (in days). The smartCleanSystem tool has a cleanLevel enum with values "safe", "normal", and "deep".